1# @ohos.hiSysEvent (System Event Logging) 2 3The **hiSysEvent** module provides the system event logging functions, such as configuring trace points, subscribing to system events, and querying system events written to the event file. 4 5> **NOTE** 6> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 7> - The APIs provided by this module are system APIs. 8 9 10## Modules to Import 11 12```js 13import hiSysEvent from '@ohos.hiSysEvent'; 14``` 15 16## EventType 17 18Enumerates event types. 19 20**System capability**: SystemCapability.HiviewDFX.HiSysEvent 21 22| Name| Value| Description| 23| -------- | -------- | -------- | 24| FAULT | 1 | Error event.| 25| STATISTIC | 2 | Statistic event.| 26| SECURITY | 3 | Security event.| 27| BEHAVIOR | 4 | User behavior event.| 28 29## SysEventInfo 30 31Defines a system event. 32 33**System capability**: SystemCapability.HiviewDFX.HiSysEvent 34 35| Name| Type| Mandatory| Description| 36| -------- | -------- | -------- | -------- | 37| domain | string | Yes| Event domain.| 38| name | string | Yes| Event name.| 39| eventType | [EventType](#eventtype) | Yes| Event type.| 40| params | object | No| Event parameters.| 41 42 43## hiSysEvent.write 44 45write(info: SysEventInfo, callback: AsyncCallback<void>): void 46 47Writes event information to the event file. This API uses an asynchronous callback to return the result. 48 49**System capability**: SystemCapability.HiviewDFX.HiSysEvent 50 51**Parameters** 52 53| Name | Type | Mandatory| Description | 54| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 55| info | [SysEventInfo](#syseventinfo) | Yes| System event information.| 56| callback | AsyncCallback<void> | Yes| Callback used to process the received return value.<br>- Value **0**: The event verification is successful, and the event will be written to the event file asynchronously. <br>- A value greater than **0**: Invalid parameters are present in the event, and the event will be written to the event file asynchronously after the invalid parameters are ignored.<br>- A value smaller than **0**: The event parameter verification fails, and the event will not be written to the event file.| 57 58**Error codes** 59 60For details about the error codes, see [HiSysEvent Error Codes](../errorcodes/errorcode-hisysevent.md). 61 62| ID| Error Message| 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**Example** 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 103Writes event information to the event file. This API uses a promise to return the result. 104 105**System capability**: SystemCapability.HiviewDFX.HiSysEvent 106 107**Parameters** 108 109| Name | Type | Mandatory| Description| 110| --------- | ----------------------- | ---- | --------------- | 111| info | [SysEventInfo](#syseventinfo) | Yes | System event information.| 112 113**Return value** 114 115| Type | Description | 116| ------------------- | ------------------------------------------------------------ | 117| Promise<void> | Promise used to return the result. Depending on whether event writing is successful, you can use the **then()** or **catch()** method to process the callback.| 118 119**Error codes** 120 121For details about the error codes, see [HiSysEvent Error Codes](../errorcodes/errorcode-hisysevent.md). 122 123| ID| Error Message| 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**Example** 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 167Enumerates matching rule types. 168 169**System capability**: SystemCapability.HiviewDFX.HiSysEvent 170 171| Name| Value| Description| 172| -------- | -------- | -------- | 173| WHOLE_WORD | 1 | Whole word matching.| 174| PREFIX | 2 | Prefix matching.| 175| REGULAR | 3 | Regular expression matching.| 176 177## WatchRule 178 179Defines event subscription rules. 180 181**System capability**: SystemCapability.HiviewDFX.HiSysEvent 182 183| Name| Type| Mandatory| Description| 184| -------- | -------- | -------- | -------- | 185| domain | string | Yes| Event domain.| 186| name | string | Yes| Event name.| 187| tag | string | No| Event tag.| 188| ruleType | [RuleType](#ruletype) | Yes| Matching rule type.| 189 190## Watcher 191 192Defines a watcher for event subscription. 193 194**System capability**: SystemCapability.HiviewDFX.HiSysEvent 195 196| Name| Type| Mandatory| Description| 197| -------- | -------- | -------- | -------- | 198| rules | [WatchRule](#watchrule)[] | Yes| Array of matching event subscription rules.| 199| onEvent | function | Yes| Callback for event subscription: (info: [SysEventInfo](#syseventinfo)) => void| 200| onServiceDied | function | Yes| Callback for disabling of event subscription: () => void| 201 202## hiSysEvent.addWatcher 203 204addWatcher(watcher: Watcher): void 205 206Adds a watcher for event subscription. 207 208**Required permission**: ohos.permission.READ_DFX_SYSEVENT 209 210**System capability**: SystemCapability.HiviewDFX.HiSysEvent 211 212**Parameters** 213 214| Name| Type| Mandatory| Description| 215| ------ | ----------------------------- | ---- | ------------------------ | 216| watcher | [Watcher](#watcher) | Yes| Watcher for event subscription.| 217 218**Error codes** 219 220For details about the error codes, see [HiSysEvent Error Codes](../errorcodes/errorcode-hisysevent.md). 221 222| ID| Error Message| 223| -------- | ----------------------------------- | 224| 11200101 | Count of watchers is over limit. | 225| 11200102 | Count of watch rules is over limit. | 226 227**Example** 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 257Removes a watcher used for event subscription. 258 259**Required permission**: ohos.permission.READ_DFX_SYSEVENT 260 261**System capability**: SystemCapability.HiviewDFX.HiSysEvent 262 263**Parameters** 264 265| Name| Type | Mandatory| Description | 266| ------ | ------------- | ---- | ------------------------- | 267| watcher | [Watcher](#watcher) | Yes| Watcher for event subscription.| 268 269**Error codes** 270 271For details about the error codes, see [HiSysEvent Error Codes](../errorcodes/errorcode-hisysevent.md). 272 273| ID| Error Message| 274| -------- | --------------------------- | 275| 11200201 | The watcher does not exist. | 276 277**Example** 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 306Defines arguments for an event query. 307 308**System capability**: SystemCapability.HiviewDFX.HiSysEvent 309 310| Name| Type| Mandatory| Description| 311| -------- | -------- | -------- | -------- | 312| beginTime | number | Yes| Start time (13-digit timestamp) for the event query.| 313| endTime | number | Yes| End time (13-digit timestamp) for the event query.| 314| maxEvents | number | Yes| Maximum number of events that can be queried.| 315 316## QueryRule 317 318Defines event query rules. 319 320**System capability**: SystemCapability.HiviewDFX.HiSysEvent 321 322| Name| Type| Mandatory| Description| 323| -------- | -------- | -------- | -------- | 324| domain | string | Yes| Event domain.| 325| names | string[] | Yes| Array of event names. A **QueryRule** object contains multiple system event names.| 326 327## Querier 328 329Defines an event query instance. 330 331**System capability**: SystemCapability.HiviewDFX.HiSysEvent 332 333| Name| Type| Mandatory| Description| 334| -------- | -------- | -------- | -------- | 335| onQuery | function | Yes| Callback used to return the queried system events: (infos: [SysEventInfo](#syseventinfo)[]) => void.| 336| onComplete | function | Yes| Callback used to return the query result statistics: (reason: number, total: number) => void| 337 338## hiSysEvent.query 339 340query(queryArg: QueryArg, rules: QueryRule[], querier: Querier): void 341 342Queries system events. 343 344**Required permission**: ohos.permission.READ_DFX_SYSEVENT 345 346**System capability**: SystemCapability.HiviewDFX.HiSysEvent 347 348**Parameters** 349 350| Name| Type| Mandatory| Description| 351| ------ | ----------------------------- | ---- | ------------------------ | 352| queryArg | [QueryArg](#queryarg) | Yes | Arguments for event query.| 353| rules | [QueryRule](#queryrule)[] | Yes | Array of event query rules.| 354| querier | [Querier](#querier) | Yes | Event query instance.| 355 356**Error codes** 357 358For details about the error codes, see [HiSysEvent Error Codes](../errorcodes/errorcode-hisysevent.md). 359 360| ID| Error Message| 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**Example** 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``` 406