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 16/** 17 * @file 18 * @kit PerformanceAnalysisKit 19 */ 20 21import { AsyncCallback } from './@ohos.base'; 22 23/** 24 * Provides the system event logging function for applications to log the fault, statistical, security, 25 * and user behavior events reported during running. Based on event information, 26 * you will be able to analyze the running status of applications. 27 * 28 * @namespace hiSysEvent 29 * @syscap SystemCapability.HiviewDFX.HiSysEvent 30 * @systemapi hide for inner use 31 * @since 9 32 */ 33declare namespace hiSysEvent { 34 /** 35 * Enumerate system event types. 36 * 37 * @enum {number} 38 * @syscap SystemCapability.HiviewDFX.HiSysEvent 39 * @systemapi hide for inner use 40 * @since 9 41 */ 42 enum EventType { 43 /** 44 * Fault event 45 * 46 * @syscap SystemCapability.HiviewDFX.HiSysEvent 47 * @systemapi hide for inner use 48 * @since 9 49 */ 50 FAULT = 1, 51 52 /** 53 * Statistic event 54 * 55 * @syscap SystemCapability.HiviewDFX.HiSysEvent 56 * @systemapi hide for inner use 57 * @since 9 58 */ 59 STATISTIC = 2, 60 61 /** 62 * Security event 63 * 64 * @syscap SystemCapability.HiviewDFX.HiSysEvent 65 * @systemapi hide for inner use 66 * @since 9 67 */ 68 SECURITY = 3, 69 70 /** 71 * System behavior event 72 * 73 * @syscap SystemCapability.HiviewDFX.HiSysEvent 74 * @systemapi hide for inner use 75 * @since 9 76 */ 77 BEHAVIOR = 4 78 } 79 80 /** 81 * Definition of written system event information. 82 * 83 * @interface SysEventInfo 84 * @syscap SystemCapability.HiviewDFX.HiSysEvent 85 * @systemapi hide for inner use 86 * @since 9 87 */ 88 interface SysEventInfo { 89 /** 90 * The domain of the event. 91 * 92 * @type { string } 93 * @syscap SystemCapability.HiviewDFX.HiSysEvent 94 * @systemapi hide for inner use 95 * @since 9 96 */ 97 domain: string; 98 99 /** 100 * The name of the event. 101 * 102 * @type { string } 103 * @syscap SystemCapability.HiviewDFX.HiSysEvent 104 * @systemapi hide for inner use 105 * @since 9 106 */ 107 name: string; 108 109 /** 110 * The type of the event. 111 * 112 * @type { EventType } 113 * @syscap SystemCapability.HiviewDFX.HiSysEvent 114 * @systemapi hide for inner use 115 * @since 9 116 */ 117 eventType: EventType; 118 119 /** 120 * The params of the event. 121 * 122 * @type { object } 123 * @syscap SystemCapability.HiviewDFX.HiSysEvent 124 * @systemapi hide for inner use 125 * @since 9 126 */ 127 /** 128 * The params of the event. 129 * 130 * @type { ?object } 131 * @syscap SystemCapability.HiviewDFX.HiSysEvent 132 * @systemapi hide for inner use 133 * @since 12 134 */ 135 params?: object; 136 } 137 138 /** 139 * Write system event. 140 * 141 * @param {SysEventInfo} info - system event information to be written. 142 * @returns {Promise<void>} - Return Promise 143 * @throws {BusinessError} 401 - Parameter error. Possible causes: 144 * 1. Mandatory parameters are left unspecified. 145 * 2. Incorrect parameter types. 146 * 3. Parameter verification failed. 147 * @throws {BusinessError} 11200001 - Invalid event domain. 148 * @throws {BusinessError} 11200002 - Invalid event name. 149 * @throws {BusinessError} 11200003 - Abnormal environment. 150 * @throws {BusinessError} 11200004 - The event length exceeds the limit. 151 * @throws {BusinessError} 11200051 - Invalid event parameter. 152 * @throws {BusinessError} 11200052 - The size of the event parameter of the string type exceeds the limit. 153 * @throws {BusinessError} 11200053 - The number of event parameters exceeds the limit. 154 * @throws {BusinessError} 11200054 - The number of event parameters of the array type exceeds the limit. 155 * @syscap SystemCapability.HiviewDFX.HiSysEvent 156 * @systemapi hide for inner use 157 * @since 9 158 */ 159 function write(info: SysEventInfo): Promise<void>; 160 161 /** 162 * Write system event. 163 * 164 * @param {SysEventInfo} info - system event information to be written. 165 * @param {AsyncCallback<void>} callback - callback function. 166 * @throws {BusinessError} 401 - Parameter error. Possible causes: 167 * 1. Mandatory parameters are left unspecified. 168 * 2. Incorrect parameter types. 169 * 3. Parameter verification failed. 170 * @throws {BusinessError} 11200001 - Invalid event domain. 171 * @throws {BusinessError} 11200002 - Invalid event name. 172 * @throws {BusinessError} 11200003 - Abnormal environment. 173 * @throws {BusinessError} 11200004 - The event length exceeds the limit. 174 * @throws {BusinessError} 11200051 - Invalid event parameter. 175 * @throws {BusinessError} 11200052 - The size of the event parameter of the string type exceeds the limit. 176 * @throws {BusinessError} 11200053 - The number of event parameters exceeds the limit. 177 * @throws {BusinessError} 11200054 - The number of event parameters of the array type exceeds the limit. 178 * @syscap SystemCapability.HiviewDFX.HiSysEvent 179 * @systemapi hide for inner use 180 * @since 9 181 */ 182 function write(info: SysEventInfo, callback: AsyncCallback<void>): void; 183 184 /** 185 * Enumerate search system event rule type. 186 * 187 * @enum {number} 188 * @syscap SystemCapability.HiviewDFX.HiSysEvent 189 * @systemapi hide for inner use 190 * @since 9 191 */ 192 enum RuleType { 193 /** 194 * Whole word match 195 * 196 * @syscap SystemCapability.HiviewDFX.HiSysEvent 197 * @systemapi hide for inner use 198 * @since 9 199 */ 200 WHOLE_WORD = 1, 201 202 /** 203 * Prefix match 204 * 205 * @syscap SystemCapability.HiviewDFX.HiSysEvent 206 * @systemapi hide for inner use 207 * @since 9 208 */ 209 PREFIX = 2, 210 211 /** 212 * Regular match 213 * 214 * @syscap SystemCapability.HiviewDFX.HiSysEvent 215 * @systemapi hide for inner use 216 * @since 9 217 */ 218 REGULAR = 3 219 } 220 221 /** 222 * Definition listener rule for system event information. 223 * 224 * @interface WatchRule 225 * @syscap SystemCapability.HiviewDFX.HiSysEvent 226 * @systemapi hide for inner use 227 * @since 9 228 */ 229 interface WatchRule { 230 /** 231 * The domain of the event. 232 * 233 * @type { string } 234 * @syscap SystemCapability.HiviewDFX.HiSysEvent 235 * @systemapi hide for inner use 236 * @since 9 237 */ 238 domain: string; 239 240 /** 241 * The name of the event. 242 * 243 * @type { string } 244 * @syscap SystemCapability.HiviewDFX.HiSysEvent 245 * @systemapi hide for inner use 246 * @since 9 247 */ 248 name: string; 249 250 /** 251 * The tag of the event. 252 * 253 * @type { string } 254 * @syscap SystemCapability.HiviewDFX.HiSysEvent 255 * @systemapi hide for inner use 256 * @since 9 257 */ 258 /** 259 * The tag of the event. 260 * 261 * @type { ?string } 262 * @syscap SystemCapability.HiviewDFX.HiSysEvent 263 * @systemapi hide for inner use 264 * @since 12 265 */ 266 tag?: string; 267 268 /** 269 * The rule of match system event 270 * 271 * @type { RuleType } 272 * @syscap SystemCapability.HiviewDFX.HiSysEvent 273 * @systemapi hide for inner use 274 * @since 9 275 */ 276 ruleType: RuleType; 277 } 278 279 /** 280 * Definition watcher for system event information. 281 * 282 * @interface Watcher 283 * @syscap SystemCapability.HiviewDFX.HiSysEvent 284 * @systemapi hide for inner use 285 * @since 9 286 */ 287 interface Watcher { 288 /** 289 * Rule of filter system event 290 * 291 * @type { WatchRule[] } 292 * @syscap SystemCapability.HiviewDFX.HiSysEvent 293 * @systemapi hide for inner use 294 * @since 9 295 */ 296 rules: WatchRule[]; 297 298 /** 299 * Receive system event. 300 * 301 * @type { function } 302 * @syscap SystemCapability.HiviewDFX.HiSysEvent 303 * @systemapi hide for inner use 304 * @since 9 305 */ 306 onEvent: (info: SysEventInfo) => void; 307 308 /** 309 * Hisysevent service shutdown. 310 * 311 * @type { function } 312 * @syscap SystemCapability.HiviewDFX.HiSysEvent 313 * @systemapi hide for inner use 314 * @since 9 315 */ 316 onServiceDied: () => void; 317 } 318 319 /** 320 * Definition arguments for query system event information. 321 * 322 * @interface QueryArg 323 * @syscap SystemCapability.HiviewDFX.HiSysEvent 324 * @systemapi hide for inner use 325 * @since 9 326 */ 327 interface QueryArg { 328 /** 329 * Begin time 330 * 331 * @type { number } 332 * @syscap SystemCapability.HiviewDFX.HiSysEvent 333 * @systemapi hide for inner use 334 * @since 9 335 */ 336 beginTime: number; 337 338 /** 339 * End time 340 * 341 * @type { number } 342 * @syscap SystemCapability.HiviewDFX.HiSysEvent 343 * @systemapi hide for inner use 344 * @since 9 345 */ 346 endTime: number; 347 348 /** 349 * Max number of receive system event 350 * 351 * @type { number } 352 * @syscap SystemCapability.HiviewDFX.HiSysEvent 353 * @systemapi hide for inner use 354 * @since 9 355 */ 356 maxEvents: number; 357 358 /** 359 * Begin sequence 360 * 361 * @type { ?number } 362 * @syscap SystemCapability.HiviewDFX.HiSysEvent 363 * @systemapi hide for inner use 364 * @since 10 365 */ 366 fromSeq?: number; 367 368 /** 369 * End sequence 370 * 371 * @type { ?number } 372 * @syscap SystemCapability.HiviewDFX.HiSysEvent 373 * @systemapi hide for inner use 374 * @since 10 375 */ 376 toSeq?: number; 377 } 378 379 /** 380 * Definition event for query system event information 381 * 382 * @interface QueryRule 383 * @syscap SystemCapability.HiviewDFX.HiSysEvent 384 * @systemapi hide for inner use 385 * @since 9 386 */ 387 interface QueryRule { 388 /** 389 * The domain of the event 390 * 391 * @type { string } 392 * @syscap SystemCapability.HiviewDFX.HiSysEvent 393 * @systemapi hide for inner use 394 * @since 9 395 */ 396 domain: string; 397 398 /** 399 * List of event name 400 * 401 * @type { string[] } 402 * @syscap SystemCapability.HiviewDFX.HiSysEvent 403 * @systemapi hide for inner use 404 * @since 9 405 */ 406 names: string[]; 407 408 /** 409 * Extra parameter condition of event 410 * 411 * @type { ?string } 412 * @syscap SystemCapability.HiviewDFX.HiSysEvent 413 * @systemapi hide for inner use 414 * @since 10 415 */ 416 condition?: string; 417 } 418 419 /** 420 * Definition query result handler 421 * 422 * @interface Querier 423 * @syscap SystemCapability.HiviewDFX.HiSysEvent 424 * @systemapi hide for inner use 425 * @since 9 426 */ 427 interface Querier { 428 /** 429 * Handle query result, the query result will be send in several times. 430 * 431 * @type { function } 432 * @syscap SystemCapability.HiviewDFX.HiSysEvent 433 * @systemapi hide for inner use 434 * @since 9 435 */ 436 onQuery: (infos: SysEventInfo[]) => void; 437 438 /** 439 * Notify querier execute query has finished. 440 * 441 * @type { function } 442 * @syscap SystemCapability.HiviewDFX.HiSysEvent 443 * @systemapi hide for inner use 444 * @since 9 445 */ 446 onComplete: (reason: number, total: number) => void; 447 } 448 449 /** 450 * Add watcher to watch system event 451 * 452 * @permission ohos.permission.READ_DFX_SYSEVENT 453 * @param {Watcher} watcher watch system event 454 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 455 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 456 * @throws {BusinessError} 401 - Parameter error. Possible causes: 457 * 1. Mandatory parameters are left unspecified. 458 * 2. Incorrect parameter types. 459 * 3. Parameter verification failed. 460 * @throws {BusinessError} 11200101 - The number of watchers exceeds the limit. 461 * @throws {BusinessError} 11200102 - The number of watch rules exceeds the limit. 462 * @syscap SystemCapability.HiviewDFX.HiSysEvent 463 * @systemapi hide for inner use 464 * @since 9 465 */ 466 function addWatcher(watcher: Watcher): void; 467 468 /** 469 * Remove watcher 470 * 471 * @permission ohos.permission.READ_DFX_SYSEVENT 472 * @param {Watcher} watcher watch system event 473 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 474 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 475 * @throws {BusinessError} 401 - Parameter error. Possible causes: 476 * 1. Mandatory parameters are left unspecified. 477 * 2. Incorrect parameter types. 478 * 3. Parameter verification failed. 479 * @throws {BusinessError} 11200201 - The watcher does not exist. 480 * @syscap SystemCapability.HiviewDFX.HiSysEvent 481 * @systemapi hide for inner use 482 * @since 9 483 */ 484 function removeWatcher(watcher: Watcher): void; 485 486 /** 487 * Query system event 488 * 489 * @permission ohos.permission.READ_DFX_SYSEVENT 490 * @param {QueryArg} queryArg common arguments of query system event 491 * @param {QueryRule[]} rules rule of query system event 492 * @param {Querier} querier receive query result 493 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 494 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 495 * @throws {BusinessError} 401 - Parameter error. Possible causes: 496 * 1. Mandatory parameters are left unspecified. 497 * 2. Incorrect parameter types. 498 * 3. Parameter verification failed. 499 * @throws {BusinessError} 11200301 - The number of query rules exceeds the limit. 500 * @throws {BusinessError} 11200302 - Invalid query rule. 501 * @throws {BusinessError} 11200303 - The number of concurrent queriers exceeds the limit. 502 * @throws {BusinessError} 11200304 - The query frequency exceeds the limit. 503 * @syscap SystemCapability.HiviewDFX.HiSysEvent 504 * @systemapi hide for inner use 505 * @since 9 506 */ 507 function query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void; 508 509 /** 510 * Export system event 511 * 512 * @permission ohos.permission.READ_DFX_SYSEVENT 513 * @param {QueryArg} queryArg common arguments of query system event 514 * @param {QueryRule[]} rules rule of query system event 515 * @returns {number} return hiview receive task time. 516 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 517 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 518 * @throws {BusinessError} 401 - Parameter error. Possible causes: 519 * 1. Mandatory parameters are left unspecified. 520 * 2. Incorrect parameter types. 521 * 3. Parameter verification failed. 522 * @throws {BusinessError} 11200301 - The number of query rules exceeds the limit. 523 * @throws {BusinessError} 11200302 - Invalid query rule. 524 * @throws {BusinessError} 11200304 – The query frequency exceeds the limit. 525 * @syscap SystemCapability.HiviewDFX.HiSysEvent 526 * @systemapi hide for inner use 527 * @since 10 528 */ 529 function exportSysEvents(queryArg: QueryArg, rules: QueryRule[]): number; 530 531 /** 532 * Subscribe system event 533 * 534 * @permission ohos.permission.READ_DFX_SYSEVENT 535 * @param {QueryRule[]} rules rule of subscribe system event 536 * @returns {number} return hiview receive task time. 537 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 538 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 539 * @throws {BusinessError} 401 - Parameter error. Possible causes: 540 * 1. Mandatory parameters are left unspecified. 541 * 2. Incorrect parameter types. 542 * 3. Parameter verification failed. 543 * @throws {BusinessError} 11200301 - The number of query rules exceeds the limit. 544 * @throws {BusinessError} 11200302 - Invalid query rule. 545 * @syscap SystemCapability.HiviewDFX.HiSysEvent 546 * @systemapi hide for inner use 547 * @since 10 548 */ 549 function subscribe(rules: QueryRule[]): number; 550 551 /** 552 * Unsubscribe system event 553 * 554 * @permission ohos.permission.READ_DFX_SYSEVENT 555 * @throws {BusinessError} 201 - Permission denied. An attempt was made to read system event forbidden by permission: ohos.permission.READ_DFX_SYSEVENT. 556 * @throws {BusinessError} 202 - System API is not allowed called by Non-system application. 557 * @throws {BusinessError} 401 - Parameter error. Possible causes: 558 * 1. Mandatory parameters are left unspecified. 559 * 2. Incorrect parameter types. 560 * 3. Parameter verification failed. 561 * @throws {BusinessError} 11200305 – Unsubscription failed. 562 * @syscap SystemCapability.HiviewDFX.HiSysEvent 563 * @systemapi hide for inner use 564 * @since 10 565 */ 566 function unsubscribe(): void; 567} 568 569export default hiSysEvent; 570