1# @ohos.hiSysEvent (系统事件打点) 2 3本模块提供了系统事件打点能力，包括系统事件的埋点、落盘系统事件的订阅及已落盘的系统事件的查询能力。 4 5> **说明：** 6> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 7> - 本模块的接口为系统接口。 8 9 10## 导入模块 11 12```js 13import hiSysEvent from '@ohos.hiSysEvent'; 14``` 15 16## EventType 17 18系统事件类型枚举。 19 20**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 21 22| 名称 | 值 | 说明 | 23| -------- | -------- | -------- | 24| FAULT | 1 | 错误事件类型。 | 25| STATISTIC | 2 | 统计事件类型。 | 26| SECURITY | 3 | 安全事件类型。 | 27| BEHAVIOR | 4 | 用户行为事件类型。 | 28 29## SysEventInfo 30 31系统事件信息对象接口。 32 33**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 34 35| 名称 | 类型 | 必填 | 说明 | 36| -------- | -------- | -------- | -------- | 37| domain | string | 是 | 事件领域。 | 38| name | string | 是 | 事件名称。 | 39| eventType | [EventType](#eventtype) | 是 | 事件类型。 | 40| params | object | 否 | 事件参数。 | 41 42 43## hiSysEvent.write 44 45write(info: SysEventInfo, callback: AsyncCallback<void>): void 46 47系统事件打点方法，接收[SysEventInfo](#syseventinfo)类型的对象作为事件参数，使用callback方式作为异步回调。 48 49**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 50 51**参数：** 52 53| 参数名 | 类型 | 必填 | 说明 | 54| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 55| info | [SysEventInfo](#syseventinfo) | 是 | 系统事件。 | 56| callback | AsyncCallback<void> | 是 | 回调函数，可以在回调函数中处理接口返回值。<br/>- 0表示事件校验成功，事件正常异步写入事件文件；<br/>- 正值表示事件打点存在异常，但可以正常写入；<br/>- 负值表示事件打点失败。 | 57 58**错误码：** 59 60以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 61 62| 错误码ID | 错误信息 | 63| ------- | ----------------------------------------------------------------- | 64| 11200001 | Invalid event domain. | 65| 11200002 | Invalid event name. | 66| 11200003 | Abnormal environment. | 67| 11200004 | Length of the event is over limit. | 68| 11200051 | Invalid event parameter. | 69| 11200052 | Size of the event parameter of the string type is over limit. | 70| 11200053 | Count of event parameters is over limit. | 71| 11200054 | Count of event parameter of the array type is over limit. | 72 73**示例：** 74 75```js 76import hiSysEvent from '@ohos.hiSysEvent'; 77 78try { 79 hiSysEvent.write({ 80 domain: "RELIABILITY", 81 name: "STACK", 82 eventType: hiSysEvent.EventType.FAULT, 83 params: { 84 PID: 487, 85 UID: 103, 86 PACKAGE_NAME: "com.ohos.hisysevent.test", 87 PROCESS_NAME: "syseventservice", 88 MSG: "no msg." 89 } 90 }, (err, val) => { 91 // do something here. 92 }) 93} catch (error) { 94 console.error(`error code: ${error.code}, error msg: ${error.message}`); 95} 96``` 97 98 99## hiSysEvent.write 100 101write(info: SysEventInfo): Promise<void> 102 103系统事件打点方法，接收[SysEventInfo](#syseventinfo)类型的对象作为事件参数，使用promise方式作为异步回调。 104 105**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 106 107**参数：** 108 109| 参数名 | 类型 | 必填 | 说明 | 110| --------- | ----------------------- | ---- | --------------- | 111| info | [SysEventInfo](#syseventinfo) | 是 | 系统事件。 | 112 113**返回值：** 114 115| 类型 | 说明 | 116| ------------------- | ------------------------------------------------------------ | 117| Promise<void> | Promise实例，可以在其then()、catch()方法中分别对系统事件写入成功、写入异常的回调进行处理。 | 118 119**错误码：** 120 121以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 122 123| 错误码ID | 错误信息 | 124| -------- | ---------------------------------------------------------------- | 125| 11200001 | Invalid event domain. | 126| 11200002 | Invalid event name. | 127| 11200003 | Abnormal environment. | 128| 11200004 | Length of the event is over limit. | 129| 11200051 | Invalid event parameter. | 130| 11200052 | Size of the event parameter of the string type is over limit. | 131| 11200053 | Count of event parameters is over limit. | 132| 11200054 | Count of event parameter of the array type is over limit. | 133 134**示例：** 135 136```js 137import hiSysEvent from '@ohos.hiSysEvent'; 138 139try { 140 hiSysEvent.write({ 141 domain: "RELIABILITY", 142 name: "STACK", 143 eventType: hiSysEvent.EventType.FAULT, 144 params: { 145 PID: 487, 146 UID: 103, 147 PACKAGE_NAME: "com.ohos.hisysevent.test", 148 PROCESS_NAME: "syseventservice", 149 MSG: "no msg." 150 } 151 }).then( 152 (val) => { 153 // do something here. 154 } 155 ).catch( 156 (err) => { 157 // do something here. 158 } 159 ) 160} catch (error) { 161 console.error(`error code: ${error.code}, error msg: ${error.message}`); 162} 163``` 164 165## RuleType 166 167匹配规则类型枚举。 168 169**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 170 171| 名称 | 值 | 说明 | 172| -------- | -------- | -------- | 173| WHOLE_WORD | 1 | 全词匹配类型。 | 174| PREFIX | 2 | 前缀匹配类型。 | 175| REGULAR | 3 | 正则匹配类型。 | 176 177## WatchRule 178 179系统事件订阅规则对象接口。 180 181**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 182 183| 名称 | 类型 | 必填 | 说明 | 184| -------- | -------- | -------- | -------- | 185| domain | string | 是 | 事件领域。 | 186| name | string | 是 | 事件名称。 | 187| tag | string | 否 | 事件标签。 | 188| ruleType | [RuleType](#ruletype) | 是 | 匹配规则类型。 | 189 190## Watcher 191 192系统事件订阅者对象接口。 193 194**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 195 196| 名称 | 类型 | 必填 | 说明 | 197| -------- | -------- | -------- | -------- | 198| rules | [WatchRule](#watchrule)[] | 是 | 订阅对象数组，每个订阅者对象包含多个订阅规则。 | 199| onEvent | function | 是 | 订阅事件的回调方法(info: [SysEventInfo](#syseventinfo)) => void。 | 200| onServiceDied | function | 是 | 系统事件服务关闭的回调方法() => void。 | 201 202## hiSysEvent.addWatcher 203 204addWatcher(watcher: Watcher): void 205 206订阅系统事件，接收[Watcher](#watcher)类型的对象作为事件参数。 207 208**需要权限：** ohos.permission.READ_DFX_SYSEVENT 209 210**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 211 212**参数：** 213 214| 参数名 | 类型 | 必填 | 说明 | 215| ------ | ----------------------------- | ---- | ------------------------ | 216| watcher | [Watcher](#watcher) | 是 | 系统事件订阅者对象。 | 217 218**错误码：** 219 220以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 221 222| 错误码ID | 错误信息 | 223| -------- | ----------------------------------- | 224| 11200101 | Count of watchers is over limit. | 225| 11200102 | Count of watch rules is over limit. | 226 227**示例：** 228 229```js 230import hiSysEvent from '@ohos.hiSysEvent'; 231 232let watcher = { 233 rules: [{ 234 domain: "RELIABILITY", 235 name: "STACK", 236 tag: "STABILITY", 237 ruleType: hiSysEvent.RuleType.WHOLE_WORD, 238 }], 239 onEvent: (info) => { 240 // do something here. 241 }, 242 onServiceDied: () => { 243 // do something here. 244 } 245} 246try { 247 hiSysEvent.addWatcher(watcher) 248} catch (error) { 249 console.error(`error code: ${error.code}, error msg: ${error.message}`); 250} 251``` 252 253## hiSysEvent.removeWatcher 254 255removeWatcher(watcher: Watcher): void 256 257取消订阅系统事件，接收[Watcher](#watcher)类型的对象作为事件参数。 258 259**需要权限：** ohos.permission.READ_DFX_SYSEVENT 260 261**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 262 263**参数：** 264 265| 参数名 | 类型 | 必填 | 说明 | 266| ------ | ------------- | ---- | ------------------------- | 267| watcher | [Watcher](#watcher) | 是 | 系统事件订阅者对象。 | 268 269**错误码：** 270 271以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 272 273| 错误码ID | 错误信息 | 274| -------- | --------------------------- | 275| 11200201 | The watcher does not exist. | 276 277**示例：** 278 279```js 280import hiSysEvent from '@ohos.hiSysEvent'; 281 282let watcher = { 283 rules: [{ 284 domain: "RELIABILITY", 285 name: "STACK", 286 tag: "STABILITY", 287 ruleType: hiSysEvent.RuleType.WHOLE_WORD, 288 }], 289 onEvent: (info) => { 290 // do something here. 291 }, 292 onServiceDied: () => { 293 // do something here. 294 } 295} 296try { 297 hiSysEvent.addWatcher(watcher) 298 hiSysEvent.removeWatcher(watcher) 299} catch (error) { 300 console.error(`error code: ${error.code}, error msg: ${error.message}`); 301} 302``` 303 304## QueryArg 305 306系统事件查询参数对象接口。 307 308**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 309 310| 名称 | 类型 | 必填 | 说明 | 311| -------- | -------- | -------- | -------- | 312| beginTime | number | 是 | 查询的系统事件起始时间（13位时间戳）。 | 313| endTime | number | 是 | 查询的系统事件结束时间（13位时间戳）。 | 314| maxEvents | number | 是 | 查询的系统事件最多条数。 | 315 316## QueryRule 317 318系统事件查询规则对象接口。 319 320**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 321 322| 名称 | 类型 | 必填 | 说明 | 323| -------- | -------- | -------- | -------- | 324| domain | string | 是 | 查询包含的事件领域。 | 325| names | string[] | 是 | 查询所包含的多个事件名称，每个查询规则对象包含多个系统事件名称。 | 326 327## Querier 328 329系统事件查询者对象接口。 330 331**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 332 333| 名称 | 类型 | 必填 | 说明 | 334| -------- | -------- | -------- | -------- | 335| onQuery | function | 是 | 返回查询到的系统事件的回调方法(infos: [SysEventInfo](#syseventinfo)[]) => void。 | 336| onComplete | function | 是 | 查询结果统计的回调方法(reason: number, total: number) => void。 | 337 338## hiSysEvent.query 339 340query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void 341 342查询系统事件。 343 344**需要权限：** ohos.permission.READ_DFX_SYSEVENT 345 346**系统能力：** SystemCapability.HiviewDFX.HiSysEvent 347 348**参数：** 349 350| 参数名 | 类型 | 必填 | 说明 | 351| ------ | ----------------------------- | ---- | ------------------------ | 352| queryArg | [QueryArg](#queryarg) | 是 | 查询需要配置的查询参数。 | 353| rules | [QueryRule](#queryrule)[] | 是 | 查询规则数组，每次查询可配置多个查询规则。 | 354| querier | [Querier](#querier) | 是 | 查询者对象，包含查询结果及结束的相关回调。 | 355 356**错误码：** 357 358以下错误码的详细介绍请参见[系统事件错误码](../errorcodes/errorcode-hisysevent.md)。 359 360| 错误码ID | 错误信息 | 361| -------- | ------------------------------------------- | 362| 11200301 | Count of query rules is over limit. | 363| 11200302 | Invalid query rule. | 364| 11200303 | Count of concurrent queriers is over limit. | 365| 11200304 | Query frequency is over limit. | 366 367**示例：** 368 369```js 370import hiSysEvent from '@ohos.hiSysEvent'; 371 372try { 373 hiSysEvent.write({ 374 domain: "RELIABILITY", 375 name: "STACK", 376 eventType: hiSysEvent.EventType.FAULT, 377 params: { 378 PID: 487, 379 UID: 103, 380 PACKAGE_NAME: "com.ohos.hisysevent.test", 381 PROCESS_NAME: "syseventservice", 382 MSG: "no msg." 383 } 384 }, (err, val) => { 385 // do something here. 386 }) 387 hiSysEvent.query({ 388 beginTime: -1, 389 endTime: -1, 390 maxEvents: 5, 391 }, [{ 392 domain: "RELIABILITY", 393 names: ["STACK"], 394 }], { 395 onQuery: function (infos) { 396 // do something here. 397 }, 398 onComplete: function(reason, total) { 399 // do something here. 400 } 401 }) 402} catch (error) { 403 console.error(`error code: ${error.code}, error msg: ${error.message}`); 404} 405```