1# @ohos.hiSysEvent (系统事件打点) 2 3本模块提供了系统事件打点能力，包括系统事件的埋点、落盘系统事件的订阅及已落盘的系统事件的查询能力。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块的接口为系统接口。 9 10 11## 导入模块 12 13```ts 14import hiSysEvent from '@ohos.hiSysEvent'; 15``` 16 17## EventType 18 19系统事件类型枚举。 20 21**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 22 23| 名称 | 值 | 说明 | 24| -------- | -------- | -------- | 25| FAULT | 1 | 错误事件类型。 | 26| STATISTIC | 2 | 统计事件类型。 | 27| SECURITY | 3 | 安全事件类型。 | 28| BEHAVIOR | 4 | 用户行为事件类型。 | 29 30## SysEventInfo 31 32系统事件信息对象接口。 33 34**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 35 36| 名称 | 类型 | 必填 | 说明 | 37| -------- | -------- | -------- | -------- | 38| domain | string | 是 | 事件领域。 | 39| name | string | 是 | 事件名称。 | 40| eventType | [EventType](#eventtype) | 是 | 事件类型。 | 41| params | object | 否 | 事件参数。 | 42 43 44## hiSysEvent.write 45 46write(info: SysEventInfo, callback: AsyncCallback<void>): void 47 48系统事件打点方法，接收[SysEventInfo](#syseventinfo)类型的对象作为事件参数，使用callback方式作为异步回调。 49 50**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 51 52**参数：** 53 54| 参数名 | 类型 | 必填 | 说明 | 55| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 56| info | [SysEventInfo](#syseventinfo) | 是 | 系统事件。 | 57| callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。<br/>- 0表示事件校验成功，事件正常异步写入事件文件；<br/>- 正值表示事件打点存在异常，但可以正常写入；<br/>- 负值表示事件打点失败。 | 58 59**错误码：** 60 61以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 62 63| 错误码ID | 错误信息 | 64| ------- | ----------------------------------------------------------------- | 65| 11200001 | Invalid event domain. | 66| 11200002 | Invalid event name. | 67| 11200003 | Abnormal environment. | 68| 11200004 | Length of the event is over limit. | 69| 11200051 | Invalid event parameter. | 70| 11200052 | Size of the event parameter of the string type is over limit. | 71| 11200053 | Count of event parameters is over limit. | 72| 11200054 | Count of event parameter of the array type is over limit. | 73 74**示例：** 75 76```ts 77import hiSysEvent from '@ohos.hiSysEvent'; 78import { BusinessError } from '@ohos.base'; 79 80try { 81 let customizedParams: Record<string, string | number> = { 82 'PID': 487, 83 'UID': 103, 84 'PACKAGE_NAME': "com.ohos.hisysevent.test", 85 'PROCESS_NAME': "syseventservice", 86 'MSG': "no msg." 87 }; 88 let eventInfo: hiSysEvent.SysEventInfo = { 89 domain: "RELIABILITY", 90 name: "STACK", 91 eventType: hiSysEvent.EventType.FAULT, 92 params: customizedParams 93 }; 94 hiSysEvent.write(eventInfo, (err: BusinessError) => { 95 // do something here. 96 }); 97} catch (err) { 98 console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`); 99} 100``` 101 102 103## hiSysEvent.write 104 105write(info: SysEventInfo): Promise<void> 106 107系统事件打点方法，接收[SysEventInfo](#syseventinfo)类型的对象作为事件参数，使用promise方式作为异步回调。 108 109**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 110 111**参数：** 112 113| 参数名 | 类型 | 必填 | 说明 | 114| --------- | ----------------------- | ---- | --------------- | 115| info | [SysEventInfo](#syseventinfo) | 是 | 系统事件。 | 116 117**返回值：** 118 119| 类型 | 说明 | 120| ------------------- | ------------------------------------------------------------ | 121| Promise<void> | Promise实例，可以在其then()、catch()方法中分别对系统事件写入成功、写入异常的回调进行处理。 | 122 123**错误码：** 124 125以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 126 127| 错误码ID | 错误信息 | 128| -------- | ---------------------------------------------------------------- | 129| 11200001 | Invalid event domain. | 130| 11200002 | Invalid event name. | 131| 11200003 | Abnormal environment. | 132| 11200004 | Length of the event is over limit. | 133| 11200051 | Invalid event parameter. | 134| 11200052 | Size of the event parameter of the string type is over limit. | 135| 11200053 | Count of event parameters is over limit. | 136| 11200054 | Count of event parameter of the array type is over limit. | 137 138**示例：** 139 140```ts 141import hiSysEvent from '@ohos.hiSysEvent'; 142import { BusinessError } from '@ohos.base'; 143 144try { 145 let customizedParams: Record<string, string | number> = { 146 'PID': 487, 147 'UID': 103, 148 'PACKAGE_NAME': "com.ohos.hisysevent.test", 149 'PROCESS_NAME': "syseventservice", 150 'MSG': "no msg." 151 }; 152 let eventInfo: hiSysEvent.SysEventInfo = { 153 domain: "RELIABILITY", 154 name: "STACK", 155 eventType: hiSysEvent.EventType.FAULT, 156 params: customizedParams 157 }; 158 hiSysEvent.write(eventInfo).then( 159 () => { 160 // do something here. 161 } 162 ).catch( 163 (err: BusinessError) => { 164 console.error(`error code: ${err.code}, error msg: ${err.message}`); 165 } 166 ); 167} catch (err) { 168 console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`); 169} 170``` 171 172## RuleType 173 174匹配规则类型枚举。 175 176**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 177 178| 名称 | 值 | 说明 | 179| -------- | -------- | -------- | 180| WHOLE_WORD | 1 | 全词匹配类型。 | 181| PREFIX | 2 | 前缀匹配类型。 | 182| REGULAR | 3 | 正则匹配类型。 | 183 184## WatchRule 185 186系统事件订阅规则对象接口。 187 188**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 189 190| 名称 | 类型 | 必填 | 说明 | 191| -------- | -------- | -------- | -------- | 192| domain | string | 是 | 事件领域。 | 193| name | string | 是 | 事件名称。 | 194| tag | string | 否 | 事件标签。 | 195| ruleType | [RuleType](#ruletype) | 是 | 匹配规则类型。 | 196 197## Watcher 198 199系统事件订阅者对象接口。 200 201**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 202 203| 名称 | 类型 | 必填 | 说明 | 204| -------- | -------- | -------- | -------- | 205| rules | [WatchRule](#watchrule)[] | 是 | 订阅对象数组，每个订阅者对象包含多个订阅规则。 | 206| onEvent | function | 是 | 订阅事件的回调方法(info: [SysEventInfo](#syseventinfo)) => void。 | 207| onServiceDied | function | 是 | 系统事件服务关闭的回调方法() => void。 | 208 209## hiSysEvent.addWatcher 210 211addWatcher(watcher: Watcher): void 212 213订阅系统事件，接收[Watcher](#watcher)类型的对象作为事件参数。 214 215**需要权限：** ohos.permission.READ_DFX_SYSEVENT 216 217**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 218 219**参数：** 220 221| 参数名 | 类型 | 必填 | 说明 | 222| ------ | ----------------------------- | ---- | ------------------------ | 223| watcher | [Watcher](#watcher) | 是 | 系统事件订阅者对象。 | 224 225**错误码：** 226 227以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 228 229| 错误码ID | 错误信息 | 230| -------- | ----------------------------------- | 231| 11200101 | Count of watchers is over limit. | 232| 11200102 | Count of watch rules is over limit. | 233 234**示例：** 235 236```ts 237import hiSysEvent from '@ohos.hiSysEvent'; 238import { BusinessError } from '@ohos.base'; 239 240let watchRules: hiSysEvent.WatchRule[] = [{ 241 domain: "RELIABILITY", 242 name: "STACK", 243 tag: "STABILITY", 244 ruleType: hiSysEvent.RuleType.WHOLE_WORD, 245 } as hiSysEvent.WatchRule]; 246let watcher: hiSysEvent.Watcher = { 247 rules: watchRules, 248 onEvent: (info: hiSysEvent.SysEventInfo) => { 249 // do something here. 250 }, 251 onServiceDied: () => { 252 // do something here. 253 } 254}; 255try { 256 hiSysEvent.addWatcher(watcher); 257} catch (err) { 258 console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`); 259} 260``` 261 262## hiSysEvent.removeWatcher 263 264removeWatcher(watcher: Watcher): void 265 266取消订阅系统事件，接收[Watcher](#watcher)类型的对象作为事件参数。 267 268**需要权限：** ohos.permission.READ_DFX_SYSEVENT 269 270**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 271 272**参数：** 273 274| 参数名 | 类型 | 必填 | 说明 | 275| ------ | ------------- | ---- | ------------------------- | 276| watcher | [Watcher](#watcher) | 是 | 系统事件订阅者对象。 | 277 278**错误码：** 279 280以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 281 282| 错误码ID | 错误信息 | 283| -------- | --------------------------- | 284| 11200201 | The watcher does not exist. | 285 286**示例：** 287 288```ts 289import hiSysEvent from '@ohos.hiSysEvent'; 290import { BusinessError } from '@ohos.base'; 291 292let watchRules: hiSysEvent.WatchRule[] = [{ 293 domain: "RELIABILITY", 294 name: "STACK", 295 tag: "STABILITY", 296 ruleType: hiSysEvent.RuleType.WHOLE_WORD, 297 } as hiSysEvent.WatchRule ]; 298let watcher: hiSysEvent.Watcher = { 299 rules: watchRules, 300 onEvent: (info: hiSysEvent.SysEventInfo) => { 301 // do something here. 302 }, 303 onServiceDied: () => { 304 // do something here. 305 } 306}; 307try { 308 hiSysEvent.addWatcher(watcher); 309 hiSysEvent.removeWatcher(watcher); 310} catch (err) { 311 console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`); 312} 313``` 314 315## QueryArg 316 317系统事件查询参数对象接口。 318 319**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 320 321| 名称 | 类型 | 必填 | 说明 | 322| -------- | -------- | -------- | -------- | 323| beginTime | number | 是 | 查询的系统事件起始时间（13位时间戳）。 | 324| endTime | number | 是 | 查询的系统事件结束时间（13位时间戳）。 | 325| maxEvents | number | 是 | 查询的系统事件最多条数。 | 326| fromSeq<sup>10+</sup> | number | 否 | 查询的系统事件起始序列号，默认值为-1。 | 327| toSeq<sup>10+</sup> | number | 否 | 查询的系统事件结束序列号，默认值为-1。 | 328 329## QueryRule 330 331系统事件查询规则对象接口。 332 333**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 334 335| 名称 | 类型 | 必填 | 说明 | 336| -------- | -------- | -------- | -------- | 337| domain | string | 是 | 查询包含的事件领域。 | 338| names | string[] | 是 | 查询所包含的多个事件名称，每个查询规则对象包含多个系统事件名称。 | 339| condition<sup>10+</sup> | string | 否 | 事件的额外参数条件，格式：{"version":"V1","condition":{"and":[{"param":"参数","op":"操作符","value":"比较值"}]}} | 340 341## Querier 342 343系统事件查询者对象接口。 344 345**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 346 347| 名称 | 类型 | 必填 | 说明 | 348| -------- | -------- | -------- | -------- | 349| onQuery | function | 是 | 返回查询到的系统事件的回调方法(infos: [SysEventInfo](#syseventinfo)[]) => void。 | 350| onComplete | function | 是 | 查询结果统计的回调方法(reason: number, total: number) => void。 | 351 352## hiSysEvent.query 353 354query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void 355 356查询系统事件。 357 358**需要权限：** ohos.permission.READ_DFX_SYSEVENT 359 360**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 361 362**参数：** 363 364| 参数名 | 类型 | 必填 | 说明 | 365| ------ | ----------------------------- | ---- | ------------------------ | 366| queryArg | [QueryArg](#queryarg) | 是 | 查询需要配置的查询参数。 | 367| rules | [QueryRule](#queryrule)[] | 是 | 查询规则数组，每次查询可配置多个查询规则。 | 368| querier | [Querier](#querier) | 是 | 查询者对象，包含查询结果及结束的相关回调。 | 369 370**错误码：** 371 372以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 373 374| 错误码ID | 错误信息 | 375| -------- | ------------------------------------------- | 376| 11200301 | Count of query rules is over limit. | 377| 11200302 | Invalid query rule. | 378| 11200303 | Count of concurrent queriers is over limit. | 379| 11200304 | Query frequency is over limit. | 380 381**示例：** 382 383```ts 384import hiSysEvent from '@ohos.hiSysEvent'; 385import { BusinessError } from '@ohos.base'; 386 387try { 388 let customizedParams: Record<string, string | number> = { 389 'PID': 487, 390 'UID': 103, 391 'PACKAGE_NAME': "com.ohos.hisysevent.test", 392 'PROCESS_NAME': "syseventservice", 393 'MSG': "no msg." 394 }; 395 let eventInfo: hiSysEvent.SysEventInfo = { 396 domain: "RELIABILITY", 397 name: "STACK", 398 eventType: hiSysEvent.EventType.FAULT, 399 params: customizedParams 400 }; 401 hiSysEvent.write(eventInfo, (err: BusinessError) => { 402 // do something here. 403 }); 404 405 let queryArg: hiSysEvent.QueryArg = { 406 beginTime: -1, 407 endTime: -1, 408 maxEvents: 5, 409 }; 410 let queryRules: hiSysEvent.QueryRule[] = [{ 411 domain: "RELIABILITY", 412 names: ["STACK"], 413 } as hiSysEvent.QueryRule]; 414 let querier: hiSysEvent.Querier = { 415 onQuery: (infos: hiSysEvent.SysEventInfo[]) => { 416 // do something here. 417 }, 418 onComplete: (reason: number, total: number) => { 419 // do something here. 420 } 421 }; 422 hiSysEvent.query(queryArg, queryRules, querier); 423} catch (err) { 424 console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`); 425} 426``` 427 428## hiSysEvent.exportSysEvents<sup>10+</sup> 429 430exportSysEvents(queryArg: QueryArg, rules: QueryRule[]): number 431 432批量导出系统事件，以文件格式写入应用沙箱固定目录(/data/storage/el2/base/cache/hiview/event/)。 433 434**需要权限：** ohos.permission.READ_DFX_SYSEVENT 435 436**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 437 438**参数：** 439 440| 参数名 | 类型 | 必填 | 说明 | 441| -------- | ------------------------- | ---- | ------------------------------------------ | 442| queryArg | [QueryArg](#queryarg) | 是 | 导出需要配置的查询参数。 | 443| rules | [QueryRule](#queryrule)[] | 是 | 查询规则数组，每次导出可配置多个查询规则。 | 444 445**返回值：** 446 447| 类型 | 说明 | 448| ------ | ---------------- | 449| number | 接口调用时间戳。 | 450 451**错误码：** 452 453以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 454 455| 错误码ID | 错误信息 | 456| -------- | ----------------------------------- | 457| 11200301 | Count of query rules is over limit. | 458| 11200302 | Invalid query rule. | 459| 11200304 | Export frequency is over limit. | 460 461**示例：** 462 463```ts 464import hiSysEvent from '@ohos.hiSysEvent'; 465import fs from '@ohos.file.fs'; 466import { BusinessError } from '@ohos.base'; 467 468try { 469 let customizedParams: Record<string, string | number> = { 470 'PID': 487, 471 'UID': 103, 472 'PACKAGE_NAME': "com.ohos.hisysevent.test", 473 'PROCESS_NAME': "syseventservice", 474 'MSG': "no msg." 475 }; 476 let eventInfo: hiSysEvent.SysEventInfo = { 477 domain: "RELIABILITY", 478 name: "STACK", 479 eventType: hiSysEvent.EventType.FAULT, 480 params: customizedParams 481 }; 482 hiSysEvent.write(eventInfo, (err: BusinessError) => { 483 // do something here. 484 }); 485 486 let queryArg: hiSysEvent.QueryArg = { 487 beginTime: -1, 488 endTime: -1, 489 maxEvents: 1, 490 }; 491 let queryRules: hiSysEvent.QueryRule[] = [{ 492 domain: "RELIABILITY", 493 names: ["STACK"], 494 } as hiSysEvent.QueryRule]; 495 let time = hiSysEvent.exportSysEvents(queryArg, queryRules); 496 console.log(`receive export task time is : ${time}`); 497 498 // 延迟读取本次导出的事件 499 setTimeout(() => { 500 let eventDir = '/data/storage/el2/base/cache/hiview/event'; 501 let filenames = fs.listFileSync(eventDir); 502 for (let i = 0; i < filenames.length; i++) { 503 if (filenames[i].indexOf(time.toString()) != -1) { 504 let res = fs.readTextSync(eventDir + '/' + filenames[i]); 505 let events: string = JSON.parse('[' + res.slice(0, res.length - 1) + ']'); 506 console.log("read file end, events is :" + JSON.stringify(events)); 507 } 508 } 509 }, 10000); 510} catch (err) { 511 console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`); 512} 513``` 514 515## hiSysEvent.subscribe<sup>10+</sup> 516 517subscribe(rules: QueryRule[]): number 518 519订阅实时系统事件(事件需满足低频率或偶发性的约束条件)，事件发生时立即以文件格式写入应用沙箱固定目录(/data/storage/el2/base/cache/hiview/event/)。 520 521**需要权限：** ohos.permission.READ_DFX_SYSEVENT 522 523**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 524 525**参数：** 526 527| 参数名 | 类型 | 必填 | 说明 | 528| ------ | ------------------------- | ---- | ------------------------------------------ | 529| rules | [QueryRule](#queryrule)[] | 是 | 查询规则数组，每次订阅可配置多个查询规则。 | 530 531**返回值：** 532 533| 类型 | 说明 | 534| ------ | ---------------- | 535| number | 接口调用时间戳。 | 536 537**错误码：** 538 539以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 540 541| 错误码ID | 错误信息 | 542| -------- | ----------------------------------- | 543| 11200301 | Count of query rules is over limit. | 544| 11200302 | Invalid query rule. | 545 546**示例：** 547 548```ts 549import hiSysEvent from '@ohos.hiSysEvent'; 550import fs from '@ohos.file.fs'; 551import { BusinessError } from '@ohos.base'; 552 553try { 554 let rules: hiSysEvent.QueryRule[] = [{ 555 domain: "RELIABILITY", 556 names: ["STACK"], 557 } as hiSysEvent.QueryRule, 558 { 559 domain: "BUNDLE_MANAGER", 560 names: ["BUNDLE_UNINSTALL"], 561 } as hiSysEvent.QueryRule]; 562 hiSysEvent.subscribe(rules); 563 564 let customizedParams: Record<string, string | number> = { 565 'PID': 487, 566 'UID': 103, 567 'PACKAGE_NAME': "com.ohos.hisysevent.test", 568 'PROCESS_NAME': "syseventservice", 569 'MSG': "no msg." 570 }; 571 let eventInfo: hiSysEvent.SysEventInfo = { 572 domain: "RELIABILITY", 573 name: "STACK", 574 eventType: hiSysEvent.EventType.FAULT, 575 params: customizedParams 576 }; 577 hiSysEvent.write(eventInfo, (err: BusinessError) => { 578 // do something here. 579 }); 580 581 // 延迟读取订阅的事件 582 setTimeout(() => { 583 let eventDir = '/data/storage/el2/base/cache/hiview/event'; 584 let filenames = fs.listFileSync(eventDir); 585 for (let i = 0; i < filenames.length; i++) { 586 let res = fs.readTextSync(eventDir + '/' + filenames[i]); 587 let events: string = JSON.parse('[' + res.slice(0, res.length - 1) + ']'); 588 console.log("read file end, events is :" + JSON.stringify(events)); 589 } 590 }, 10000); 591} catch (err) { 592 console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`); 593} 594``` 595 596## hiSysEvent.unsubscribe<sup>10+</sup> 597 598unsubscribe(): void 599 600取消订阅系统事件。 601 602**需要权限：** ohos.permission.READ_DFX_SYSEVENT 603 604**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 605 606**错误码：** 607 608以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 609 610| 错误码ID | 错误信息 | 611| -------- | ------------------- | 612| 11200305 | Unsubscribe failed. | 613 614**示例：** 615 616```ts 617import hiSysEvent from '@ohos.hiSysEvent'; 618import { BusinessError } from '@ohos.base'; 619 620try { 621 let rules: hiSysEvent.QueryRule[] = [{ 622 domain: "RELIABILITY", 623 names: ["STACK"], 624 } as hiSysEvent.QueryRule, 625 { 626 domain: "BUNDLE_MANAGER", 627 names: ["BUNDLE_UNINSTALL"], 628 } as hiSysEvent.QueryRule]; 629 hiSysEvent.subscribe(rules); 630 hiSysEvent.unsubscribe(); 631} catch (err) { 632 console.error(`error code: ${(err as BusinessError).code}, error msg: ${(err as BusinessError).message}`); 633} 634``` 635 636