1/* 2 * Copyright (c) 2022 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16import { AsyncCallback } from './basic'; 17 18/** 19 * Provides the event logging function for applications to log the fault, statistical, security, 20 * and user behavior events reported during running. Based on event information, 21 * you will be able to analyze the running status of applications. 22 * 23 * @since 9 24 * @syscap SystemCapability.HiviewDFX.HiAppEvent 25 */ 26declare namespace hiAppEvent { 27 /** 28 * Enumerate application event types. 29 * 30 * @since 9 31 * @syscap SystemCapability.HiviewDFX.HiAppEvent 32 */ 33 enum EventType { 34 /** 35 * Fault event. 36 * 37 * @since 9 38 * @syscap SystemCapability.HiviewDFX.HiAppEvent 39 */ 40 FAULT = 1, 41 42 /** 43 * Statistic event. 44 * 45 * @since 9 46 * @syscap SystemCapability.HiviewDFX.HiAppEvent 47 */ 48 STATISTIC = 2, 49 50 /** 51 * Security event. 52 * 53 * @since 9 54 * @syscap SystemCapability.HiviewDFX.HiAppEvent 55 */ 56 SECURITY = 3, 57 58 /** 59 * User behavior event. 60 * 61 * @since 9 62 * @syscap SystemCapability.HiviewDFX.HiAppEvent 63 */ 64 BEHAVIOR = 4 65 } 66 67 /** 68 * Preset event. 69 * 70 * @since 9 71 * @syscap SystemCapability.HiviewDFX.HiAppEvent 72 */ 73 namespace event { 74 /** 75 * User login event. 76 * 77 * @since 9 78 * @syscap SystemCapability.HiviewDFX.HiAppEvent 79 */ 80 const USER_LOGIN: string; 81 82 /** 83 * User logout event. 84 * 85 * @since 9 86 * @syscap SystemCapability.HiviewDFX.HiAppEvent 87 */ 88 const USER_LOGOUT: string; 89 90 /** 91 * Distributed service event. 92 * 93 * @since 9 94 * @syscap SystemCapability.HiviewDFX.HiAppEvent 95 */ 96 const DISTRIBUTED_SERVICE_START: string; 97 } 98 99 /** 100 * Preset param. 101 * 102 * @since 9 103 * @syscap SystemCapability.HiviewDFX.HiAppEvent 104 */ 105 namespace param { 106 /** 107 * User id. 108 * 109 * @since 9 110 * @syscap SystemCapability.HiviewDFX.HiAppEvent 111 */ 112 const USER_ID: string; 113 114 /** 115 * Distributed service name. 116 * 117 * @since 9 118 * @syscap SystemCapability.HiviewDFX.HiAppEvent 119 */ 120 const DISTRIBUTED_SERVICE_NAME: string; 121 122 /** 123 * Distributed service instance id. 124 * 125 * @since 9 126 * @syscap SystemCapability.HiviewDFX.HiAppEvent 127 */ 128 const DISTRIBUTED_SERVICE_INSTANCE_ID: string; 129 } 130 131 /** 132 * Application event logging configuration interface. 133 * 134 * @since 9 135 * @syscap SystemCapability.HiviewDFX.HiAppEvent 136 * @static 137 * @param {ConfigOption} config Application event logging configuration item object. 138 * @throws {BusinessError} 401 - Parameter error. 139 * @throws {BusinessError} 11103001 - Invalid max storage quota value. 140 */ 141 function configure(config: ConfigOption): void; 142 143 /** 144 * Describe the options for the configuration. 145 * 146 * @since 9 147 * @syscap SystemCapability.HiviewDFX.HiAppEvent 148 */ 149 interface ConfigOption { 150 /** 151 * Configuration item: application event logging switch. 152 * 153 * @since 9 154 * @syscap SystemCapability.HiviewDFX.HiAppEvent 155 */ 156 disable?: boolean; 157 158 /** 159 * Configuration item: event file directory storage quota size. 160 * 161 * @since 9 162 * @syscap SystemCapability.HiviewDFX.HiAppEvent 163 */ 164 maxStorage?: string; 165 } 166 167 /** 168 * Definition of written application event information. 169 * 170 * @since 9 171 * @syscap SystemCapability.HiviewDFX.HiAppEvent 172 */ 173 interface AppEventInfo { 174 /** 175 * The domain of the event. 176 */ 177 domain: string; 178 179 /** 180 * The name of the event. 181 */ 182 name: string; 183 184 /** 185 * The type of the event. 186 */ 187 eventType: EventType; 188 189 /** 190 * The params of the event. 191 */ 192 params: object; 193 } 194 195 /** 196 * Write application event. 197 * 198 * @since 9 199 * @syscap SystemCapability.HiviewDFX.HiAppEvent 200 * @static 201 * @param {AppEventInfo} info Application event information to be written. 202 * @param {AsyncCallback} [callback] Callback function. 203 * @throws {BusinessError} 401 - Parameter error. 204 * @throws {BusinessError} 11100001 - Function is disabled. 205 * @throws {BusinessError} 11101001 - Invalid event domain. 206 * @throws {BusinessError} 11101002 - Invalid event name. 207 * @throws {BusinessError} 11101003 - Invalid number of event parameters. 208 * @throws {BusinessError} 11101004 - Invalid string length of the event parameter. 209 * @throws {BusinessError} 11101005 - Invalid event parameter name. 210 * @throws {BusinessError} 11101006 - Invalid array length of the event parameter. 211 */ 212 function write(info: AppEventInfo): Promise<void>; 213 function write(info: AppEventInfo, callback: AsyncCallback<void>): void; 214 215 /** 216 * Definition of the read event package. 217 * 218 * @since 9 219 * @syscap SystemCapability.HiviewDFX.HiAppEvent 220 */ 221 interface AppEventPackage { 222 /** 223 * The id of the package. 224 */ 225 packageId: number; 226 227 /** 228 * The number of events contained in the package. 229 */ 230 row: number; 231 232 /** 233 * The total size of events contained in the package. 234 */ 235 size: number; 236 237 /** 238 * The events data contained in the package. 239 */ 240 data: string[]; 241 } 242 243 /** 244 * Definition of event holder object, which is used to read the event data monitored by the watcher. 245 * 246 * @since 9 247 * @syscap SystemCapability.HiviewDFX.HiAppEvent 248 */ 249 class AppEventPackageHolder { 250 /** 251 * Constructor for AppEventPackageHolder. 252 * 253 * @since 9 254 * @syscap SystemCapability.HiviewDFX.HiAppEvent 255 * @param {string} watcherName Name of the watcher to read. 256 */ 257 constructor(watcherName: string); 258 259 /** 260 * Set the threshold size per read. 261 * 262 * @since 9 263 * @syscap SystemCapability.HiviewDFX.HiAppEvent 264 * @param {number} size Threshold size. 265 * @throws {BusinessError} 401 - Parameter error. 266 * @throws {BusinessError} 11104001 - Invalid size value. 267 */ 268 setSize(size: number): void; 269 270 /** 271 * Read the event data monitored by the watcher. 272 * 273 * @since 9 274 * @syscap SystemCapability.HiviewDFX.HiAppEvent 275 * @returns {AppEventPackage} The read event package. 276 */ 277 takeNext(): AppEventPackage; 278 } 279 280 /** 281 * Definition of the condition for triggering callback when the watcher monitors event data. 282 * 283 * @since 9 284 * @syscap SystemCapability.HiviewDFX.HiAppEvent 285 */ 286 interface TriggerCondition { 287 /** 288 * The number of write events that trigger callback. 289 */ 290 row?: number; 291 292 /** 293 * The size of write events that trigger callback. 294 */ 295 size?: number; 296 297 /** 298 * The interval for triggering callback. 299 */ 300 timeOut?: number; 301 } 302 303 /** 304 * Definition of event filter object, which is used to filter events monitored by the watcher. 305 * 306 * @since 9 307 * @syscap SystemCapability.HiviewDFX.HiAppEvent 308 */ 309 interface AppEventFilter { 310 /** 311 * The name of the event domain to be monitored by the watcher. 312 */ 313 domain: string; 314 315 /** 316 * The types of the events to be monitored by the watcher. 317 */ 318 eventTypes?: EventType[]; 319 } 320 321 /** 322 * Definition of event watcher object, which is used to monitor written event data. 323 * 324 * @since 9 325 * @syscap SystemCapability.HiviewDFX.HiAppEvent 326 */ 327 interface Watcher { 328 /** 329 * The name of watcher. 330 */ 331 name: string; 332 333 /** 334 * The condition for triggering callback. 335 */ 336 triggerCondition?: TriggerCondition; 337 338 /** 339 * The event filters for monitoring events. 340 */ 341 appEventFilters?: AppEventFilter[]; 342 343 /** 344 * The callback function of watcher. 345 */ 346 onTrigger?: (curRow: number, curSize: number, holder: AppEventPackageHolder) => void; 347 } 348 349 /** 350 * Add event watcher. 351 * 352 * @since 9 353 * @syscap SystemCapability.HiviewDFX.HiAppEvent 354 * @static 355 * @param {Watcher} watcher Watcher object for monitoring events. 356 * @returns {AppEventPackageHolder} Holder object, which is used to read the monitoring data of the watcher. 357 * @throws {BusinessError} 401 - Parameter error. 358 * @throws {BusinessError} 11102001 - Invalid watcher name. 359 * @throws {BusinessError} 11102002 - Invalid filtering event domain. 360 * @throws {BusinessError} 11102003 - Invalid row value. 361 * @throws {BusinessError} 11102004 - Invalid size value. 362 * @throws {BusinessError} 11102005 - Invalid timeout value. 363 */ 364 function addWatcher(watcher: Watcher): AppEventPackageHolder; 365 366 /** 367 * Remove event watcher. 368 * 369 * @since 9 370 * @syscap SystemCapability.HiviewDFX.HiAppEvent 371 * @static 372 * @param {Watcher} watcher Watcher object for monitoring events. 373 * @throws {BusinessError} 401 - Parameter error. 374 * @throws {BusinessError} 11102001 - Invalid watcher name. 375 */ 376 function removeWatcher(watcher: Watcher): void; 377 378 /** 379 * Clear all local logging data of the application. 380 * 381 * @since 9 382 * @syscap SystemCapability.HiviewDFX.HiAppEvent 383 * @static 384 */ 385 function clearData(): void; 386} 387 388export default hiAppEvent; 389