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