1# HiAppEvent 2 3This module provides the application event logging functions, such as writing application events to the event file and managing the event logging configuration. 4 5> **NOTE**<br> 6> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 7 8 9## Modules to Import 10 11```js 12import hiAppEvent from '@ohos.hiAppEvent'; 13``` 14 15 16## hiAppEvent.write 17 18write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback<void>): void 19 20Writes event information to the event file of the current day. This API supports JSON parameters and uses an asynchronous callback to return the result. 21 22**System capability**: SystemCapability.HiviewDFX.HiAppEvent 23 24**Parameters** 25 26| Name | Type | Mandatory| Description | 27| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 28| eventName | string | Yes | Application event name.<br>You need to customize the event name. It can contain a maximum of 48 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter. | 29| eventType | [EventType](#eventtype) | Yes | Application event type. | 30| keyValues | object | Yes | Parameter key-value pair. For a variable-length parameter, enter each pair of parameter name and value in sequence. For a JSON parameter, enter the parameter name as the key and parameter value as the value.<br>- A key must be a string, and a value must be a string, number, boolean, or Array (which can only be a string, number, or boolean).<br>- The number of event parameters must be less than or equal to 32.<br>- The parameter name can contain a maximum of 16 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter and cannot end with an underscore (\_).<br>- A string value can contain a maximum of 8*1024 characters.<br>- An array value can contain a maximum of 100 elements. Excess elements will be truncated. | 31| callback | AsyncCallback<void> | No | Callback used to process the received return value.<br>- Value **0** indicates that the event verification is successful, and the event will be written to the event file asynchronously. <br>- A value greater than **0** indicates that 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** indicates that the event verification fails, and the event will not be written to the event file. | 32 33**Example** 34 35```js 36hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}, (err, value) => { 37 if (err) { 38 // Event writing exception: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. 39 console.error(`failed to write event because ${err.code}`); 40 return; 41 } 42 43 // Event writing succeeded. 44 console.log(`success to write event: ${value}`); 45}); 46``` 47 48 49## hiAppEvent.write 50 51write(eventName: string, eventType: EventType, keyValues: object): Promise<void> 52 53Writes event information to the event file of the current day. This API supports JSON parameters and uses a promise to return the result. 54 55**System capability**: SystemCapability.HiviewDFX.HiAppEvent 56 57**Parameters** 58 59| Name | Type | Mandatory| Description | 60| --------- | ----------------------- | ---- | ------------------------------------------------------------ | 61| eventName | string | Yes | Application event name.<br>You need to customize the event name. It can contain a maximum of 48 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter. | 62| eventType | [EventType](#eventtype) | Yes | Application event type. | 63| keyValues | object | Yes | Parameter key-value pair. For a variable-length parameter, enter each pair of parameter name and value in sequence. For a JSON parameter, enter the parameter name as the key and parameter value as the value.<br>- A key must be a string, and a value must be a string, number, boolean, or Array (which can only be a string, number, or boolean).<br>- The number of event parameters must be less than or equal to 32.<br>- The parameter name can contain a maximum of 16 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter and cannot end with an underscore (\_).<br>- A string value can contain a maximum of 8*1024 characters.<br>- An array value can contain a maximum of 100 elements. Excess elements will be truncated. | 64 65**Return value** 66 67| Type | Description | 68| ------------------- | ------------------------------------------------------------ | 69| Promise<void> | Promise used to process the callback in the then() and catch() methods when event writing succeeded or failed. | 70 71**Example** 72 73```js 74hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}) 75 .then((value) => { 76 // Event writing succeeded. 77 console.log(`success to write event: ${value}`); 78 }).catch((err) => { 79 // Event writing exception: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. 80 console.error(`failed to write event because ${err.code}`); 81 }); 82``` 83 84 85## hiAppEvent.configure 86 87configure(config: ConfigOption): boolean 88 89Configures the application event logging function, such as setting the event logging switch and maximum size of the directory that stores the event logging files. 90 91**System capability**: SystemCapability.HiviewDFX.HiAppEvent 92 93**Parameters** 94 95| Name| Type | Mandatory| Description | 96| ------ | ----------------------------- | ---- | ------------------------ | 97| config | [ConfigOption](#configoption) | Yes | Configuration items for application event logging. | 98 99**Return value** 100 101| Type | Description | 102| ------- | ----------------------------------------------------------- | 103| boolean | Returns **true** if the configuration is successful; returns **false** otherwise. | 104 105**Example** 106```js 107// Set the application event logging switch. 108hiAppEvent.configure({ 109 disable: true 110}); 111 112// Configure the maximum size of the directory that stores the event logging files. 113hiAppEvent.configure({ 114 maxStorage: '100M' 115}); 116``` 117 118 119## ConfigOption 120 121Provides the configuration items for application event logging. 122 123**System capability**: SystemCapability.HiviewDFX.HiAppEvent 124 125| Name | Type | Mandatory| Description | 126| ---------- | ------- | ---- | ------------------------------------------------------------ | 127| disable | boolean | No | Application event logging switch. The value <b>true</b> means to disable the application event logging function, and the value <b>false</b> means the opposite. | 128| maxStorage | string | No | Maximum size of the event file storage directory. The default value is **10M**. If the specified size is exceeded, the oldest event logging files in the storage directory will be deleted to free up space. | 129 130 131## EventType 132 133Enumerates event types. 134 135**System capability**: SystemCapability.HiviewDFX.HiAppEvent 136 137| Name | Default Value| Description | 138| --------- | ------ | -------------- | 139| FAULT | 1 | Fault event| 140| STATISTIC | 2 | Statistical event| 141| SECURITY | 3 | Security event| 142| BEHAVIOR | 4 | Behavior event| 143 144 145## Event 146 147Provides constants that define the names of all predefined events. 148 149**System capability**: SystemCapability.HiviewDFX.HiAppEvent 150 151| Name | Type| Readable| Writable| Description | 152| ------------------------- | -------- | ---- | ---- | -------------------- | 153| USER_LOGIN | string | Yes | No | User login event. | 154| USER_LOGOUT | string | Yes | No | User logout event. | 155| DISTRIBUTED_SERVICE_START | string | Yes | No | Distributed service startup event. | 156 157 158## Param 159 160Provides constants that define the names of all predefined event parameters. 161 162**System capability**: SystemCapability.HiviewDFX.HiAppEvent 163 164| Name | Type | Readable | Writable | Description | 165| ------------------------------- | -------- | ---- | ---- | ------------------ | 166| USER_ID | string | Yes | No | Custom user ID. | 167| DISTRIBUTED_SERVICE_NAME | string | Yes | No | Distributed service name. | 168| DISTRIBUTED_SERVICE_INSTANCE_ID | string | Yes | No | Distributed service instance ID. |