1# HiAppEvent<a name="EN-US_TOPIC_0000001162014029"></a> 2 3- [Introduction](#section11660541593) 4- [Directory Structure](#section161941989596) 5- [Compilation and Building](#section137768191623) 6- [Usage](#section1312121216216) 7 - [Available APIs](#section1551164914237) 8 - [How to Use](#section129654513264) 9 10- [Repositories Involved](#section1371113476307) 11 12## Introduction<a name="section11660541593"></a> 13 14HiAppEvent is an OpenHarmony module that provides the event logging function for applications to log the fault, statistical, security, and user behavior events reported during running. Based on event information, you will be able to analyze the running status of applications. 15 16<strong>Figure 1</strong> HiAppEvent architecture<a name="fig32154874419"></a> 17 18 19## Directory Structure<a name="section161941989596"></a> 20 21``` 22/base/hiviewdfx/hiappevent # HiAppEvent source code 23├── frameworks # Framework code 24│ └── native # Native implementation code of logging APIs 25├── interfaces # External APIs 26│ └── js # JS APIs 27│ └── innerkits # JS API implementation code 28│ └── napi # JS APIs implemented based on NAPI 29├── test # Test cases 30``` 31 32## Compilation and Building<a name="section137768191623"></a> 33 34Use Clang 8.0.0 and C++11 or higher. 35 36## Usage<a name="section1312121216216"></a> 37 38### Available APIs<a name="section1551164914237"></a> 39 40#### JS APIs 41 42<strong>Table 1</strong> JS APIs for event logging 43 44<a name="table107919166559"></a> 45<table><thead align="left"><tr id="row1880201655520"><th class="cellrowborder" valign="top" width="15.981598159815983%" id="mcps1.2.4.1.1"><p id="p5801164558"><a name="p5801164558"></a><a name="p5801164558"></a>Module</p> 46</th> 47<th class="cellrowborder" valign="top" width="50.68506850685068%" id="mcps1.2.4.1.2"><p id="p168019163559"><a name="p168019163559"></a><a name="p168019163559"></a>API</p> 48</th> 49<th class="cellrowborder" valign="top" width="33.33333333333333%" id="mcps1.2.4.1.3"><p id="p780101685516"><a name="p780101685516"></a><a name="p780101685516"></a>Description</p> 50</th> 51</tr> 52</thead> 53<tbody><tr id="row148011162552"><td class="cellrowborder" valign="top" width="15.981598159815983%" headers="mcps1.2.4.1.1 "><p id="p188061611553"><a name="p188061611553"></a><a name="p188061611553"></a>hiAppEvent</p> 54</td> 55<td class="cellrowborder" valign="top" width="50.68506850685068%" headers="mcps1.2.4.1.2 "><p id="p1880171695519"><a name="p1880171695519"></a><a name="p1880171695519"></a>write(string eventName, EventType type, object keyValues, AsyncCallback<void> callback): void</p> 56</td> 57<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p983410810310"><a name="p983410810310"></a><a name="p983410810310"></a>Logs application events in asynchronous mode. This function uses an asynchronous callback to return the result.</p> 58<p id="p683519817319"><a name="p683519817319"></a><a name="p683519817319"></a>Input arguments:</p> 59<a name="ul108351681336"></a><a name="ul108351681336"></a><ul id="ul108351681336"><li><strong>eventName</strong>: indicates the event name. </li><li><strong>type</strong>: indicates the event type. </li><li><strong>keyValues</strong>: indicates the key-value pairs of event parameters. The value is in the JSON format. </li><li><strong>callback</strong>: indicates the callback used to process the received return value. The value <strong>0</strong> indicates that the event parameter verification is successful, and the event will be written to the event file asynchronously. A value greater than <strong>0</strong> 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. A value smaller than <strong>0</strong> indicates that the event parameter verification fails, and the event will not be written to the event file asynchronously.</li></ul> 60</td> 61</tr> 62<tr id="row78021665512"><td class="cellrowborder" valign="top" width="15.981598159815983%" headers="mcps1.2.4.1.1 "><p id="p1380916165510"><a name="p1380916165510"></a><a name="p1380916165510"></a>hiAppEvent</p> 63</td> 64<td class="cellrowborder" valign="top" width="50.68506850685068%" headers="mcps1.2.4.1.2 "><p id="p1380161665518"><a name="p1380161665518"></a><a name="p1380161665518"></a>write(string eventName, EventType type, object keyValues): Promise<void></p> 65</td> 66<td class="cellrowborder" valign="top" width="33.33333333333333%" headers="mcps1.2.4.1.3 "><p id="p12532811415"><a name="p12532811415"></a><a name="p12532811415"></a>Logs application events in asynchronous mode. This function uses a promise to return the result.</p> 67<p id="p75313814417"><a name="p75313814417"></a><a name="p75313814417"></a>Input arguments: same as those in the preceding function</p> 68</td> 69</tr> 70</tbody> 71</table> 72 73<strong>Table 2</strong> JS event types (EventType) 74 75| Type| Description| 76| --------- | -------------- | 77| FAULT | Fault event| 78| STATISTIC | Statistical event| 79| SECURITY | Security event| 80| BEHAVIOR | Behavior event| 81 82<strong>Table 3</strong> JS APIs for event logging configuration 83 84<table> 85 <tr> 86 <td><strong>Module</strong></td> 87 <td><strong>API</strong></td> 88 <td><strong>Description</strong></td> 89 </tr> 90 <tr> 91 <td>hiAppEvent</td> 92 <td>configure(config: ConfigOption): boolean</td> 93 <td>Sets the configuration options for application event logging. <br/>Input arguments:<ul><li><strong>config</strong>: indicates configuration options for application event logging. </li></ul>Return value: The value <strong>true</strong> indicates the operation is successful, and the value <strong>false</strong> indicates the opposite.</td> 94 </tr> 95</table> 96 97<strong>Table 4</strong> JS logging configuration options (ConfigOption) 98 99| Name| Type| Mandatory| Description| 100| ---------- | ------- | ---- | ------------------------------------------------------------ | 101| disable | boolean | No| Application event logging switch. The value <strong>true</strong> means to disable the application event logging function, and the value <strong>false</strong> means the opposite.| 102| maxStorage | string | No| Maximum size of the event file storage directory. The default value is <strong>10M</strong>. If the specified size is exceeded, the oldest event logging files in the directory will be deleted to free up space.| 103 104<strong>Table 5</strong> JS predefined event name constants (Event) 105 106| Constant| Type| Description| 107| ------------------------- | ------ | -------------------- | 108| USER_LOGIN | string | User login event.| 109| USER_LOGOUT | string | User logout event.| 110| DISTRIBUTED\_SERVICE\_START| string | Distributed service startup event.| 111 112<strong>Table 6</strong> JS predefined parameter name constants (Param) 113 114| Constant| Type| Description| 115| ------------------------------- | ------ | ------------------ | 116| USER_ID | string | Custom user ID.| 117| DISTRIBUTED\_SERVICE\_NAME| string | Distributed service name.| 118| DISTRIBUTED\_SERVICE\_INSTANCE\_ID| string | Distributed service instance ID.| 119 120#### Native APIs 121 122<strong>Table 1</strong> Native APIs for event logging 123 124<table> 125 <tr> 126 <td><strong>API</strong></td> 127 <td><strong>Return Value</strong></td> 128 <td><strong>Description</strong></td> 129 </tr> 130 <tr> 131 <td>OH_HiAppEvent_Write(const char* domain, const char* name, enum EventType type, const ParamList list)</td> 132 <td>int</td> 133 <td>Implements logging of application events. <br/>Input arguments: 134 <ul> 135 <li><strong>domain</strong>: indicates the event domain.</li> 136 <li><strong>name</strong>: indicates the event name.</li> 137 <li><strong>type</strong>: indicates the event type.</li> 138 <li><strong>list</strong>: indicates the event parameter list. It is actually a pointer to the the linked list head node — <strong>ParamListNode*</strong>. Each parameter in the list consists of a parameter name and a parameter value.</li> 139 </ul>Return value: error code in the int format. 140 </td> 141 </tr> 142</table> 143 144<strong>Table 2</strong> Native APIs for constructing ParamList 145 146| API| Return Value| Description| 147| ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 148| OH\_HiAppEvent\_CreateParamList()| ParamList | Creates a <strong>ParamList</strong> node. A pointer to the created node is returned.| 149| OH_HiAppEvent_DestroyParamList(ParamList list) | void | Deletes <strong>ParamList</strong> nodes one by one from the head node and releases the memory.| 150| OH_HiAppEvent_AddBoolParam(ParamList list, const char* name, bool boolean) | ParamList | Creates a parameter node of the <strong>bool</strong> type and adds it to <strong>ParamList</strong>.| 151| OH_HiAppEvent_AddBoolArrayParam(ParamList list, const char* name, const bool* booleans, int arrSize) | ParamList | Creates a parameter node of the <strong>bool</strong> array type and adds it to <strong>ParamList</strong>.| 152| OH_HiAppEvent_AddInt8Param(ParamList list, const char* name, int8_t num) | ParamList | Creates a parameter node of the <strong>int8_t</strong> type and adds it to <strong>ParamList</strong>.| 153| OH_HiAppEvent_AddInt8ArrayParam(ParamList list, const char* name, const int8_t* nums, int arrSize) | ParamList | Creates a parameter node of the <strong>int8_t</strong> array type and adds it to <strong>ParamList</strong>.| 154| OH_HiAppEvent_AddInt16Param(ParamList list, const char* name, int16_t num) | ParamList | Creates a parameter node of the <strong>int16_t</strong> type and adds it to <strong>ParamList</strong>.| 155| OH_HiAppEvent_AddInt16ArrayParam(ParamList list, const char* name, const int16_t* nums, int arrSize) | ParamList | Creates a parameter node of the <strong>int16_t</strong> array type and adds it to <strong>ParamList</strong>.| 156| OH_HiAppEvent_AddInt32Param(ParamList list, const char* name, int32_t num) | ParamList | Creates a parameter node of the <strong>int32_t</strong> type and adds it to <strong>ParamList</strong>.| 157| OH_HiAppEvent_AddInt32ArrayParam(ParamList list, const char* name, const int32_t* nums, int arrSize) | ParamList | Creates a parameter node of the <strong>int32_t</strong> array type and adds it to <strong>ParamList</strong>.| 158| OH_HiAppEvent_AddInt64Param(ParamList list, const char* name, int64_t num) | ParamList | Creates a parameter node of the <strong>int64_t</strong> type and adds it to <strong>ParamList</strong>.| 159| OH_HiAppEvent_AddInt64ArrayParam(ParamList list, const char* name, const int64_t* nums, int arrSize) | ParamList | Creates a parameter node of the <strong>int64_t</strong> array type and adds the node to <strong>ParamList</strong>.| 160| OH_HiAppEvent_AddFloatParam(ParamList list, const char* name, float num) | ParamList | Creates a parameter node of the <strong>float</strong> type and adds it to <strong>ParamList</strong>.| 161| OH_HiAppEvent_AddFloatArrayParam(ParamList list, const char* name, const float* nums, int arrSize) | ParamList | Creates a parameter node of the <strong>float</strong> array type and adds it to <strong>ParamList</strong>.| 162| OH_HiAppEvent_AddDoubleParam(ParamList list, const char* name, double num) | ParamList | Creates a parameter node of the <strong>double</strong> type and adds it to <strong>ParamList</strong>.| 163| OH_HiAppEvent_AddDoubleArrayParam(ParamList list, const char* name, const double* nums, int arrSize) | ParamList | Creates a parameter node of the <strong>double</strong> array type and adds it to <strong>ParamList</strong>.| 164| OH_HiAppEvent_AddStringParam(ParamList list, const char* name, const char* str) | ParamList | Creates a parameter node of the <strong>char*</strong> type and adds it to <strong>ParamList</strong>.| 165| OH_HiAppEvent_AddStringArrayParam(ParamList list, const char* name, const char * const *strs, int arrSize) | ParamList | Creates a parameter node of the <strong>char*</strong> array type and adds it to <strong>ParamList</strong>.| 166 167<strong>Table 3</strong> Native APIs for event logging configuration 168 169<table> 170 <tr> 171 <td><strong>API</strong></td> 172 <td><strong>Return Value</strong></td> 173 <td><strong>Description</strong></td> 174 </tr> 175 <tr> 176 <td>OH_HiAppEvent_Configure(const char* name, const char* value)</td> 177 <td>bool</td> 178 <td>Sets the configuration options for application event logging. <br/>Input arguments: 179 <ul> 180 <li><strong>name</strong>: indicates the name of a configuration item. You can pass a predefined configuration item constant.</li> 181 <li><strong>value</strong>: indicates the value of the configuration item.</li> 182 </ul>Return value: The value <strong>true</strong> indicates the operation is successful, and the value <strong>false</strong> indicates the opposite. 183 </td> 184 </tr> 185</table> 186 187<strong>Table 4</strong> Predefined configuration item constants 188 189| Constant| Type| Description| 190| ----------- | ------------ | ------------------------------------------------------------ | 191| DISABLE | const char[] | Sets the application event logging switch. The value <strong>true</strong> means to disable the application event logging function, and the value <strong>false</strong> means the opposite.| 192| MAX_STORAGE | const char[] | Specifies the maximum size of the event file storage directory. The default value is <strong>10M</strong>.| 193 194<strong>Table 5</strong> Predefined event name constants 195 196| Constant| Type| Description| 197| ------------------------------- | ------------ | ------------------------ | 198| EVENT_USER_LOGIN | const char[] | Name of the user login event.| 199| EVENT_USER_LOGOUT | const char[] | Name of the user logout event.| 200| EVENT_DISTRIBUTED_SERVICE_START | const char[] | Name of the distributed service startup event.| 201 202<strong>Table 6</strong> Predefined parameter name constants 203 204| Constant| Type| Description| 205| ------------------------------------- | ------------ | ------------------ | 206| PARAM_USER_ID | const char[] | Custom user ID.| 207| PARAM_DISTRIBUTED_SERVICE_NAME | const char[] | Distributed service name.| 208| PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID | const char[] | Distributed service instance ID.| 209 210### How to Use<a name="section129654513264"></a> 211 212#### JS 213 2141. Develop the source code. 215 216 Import the HiAppEvent module. 217 218 ```js 219 import hiAppEvent from '@ohos.hiAppEvent' 220 ``` 221 2222. Log application events. 223 224 ```js 225 // Callback mode 226 hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}, (err, value) => { 227 if (err) { 228 // Event writing failed: The event contains invalid parameters or the event parameter verification fails. 229 console.error(`failed to write event because ${err.code}`); 230 return; 231 } 232 233 // Event writing succeeded. 234 console.log(`success to write event: ${value}`); 235 }); 236 237 // Promise mode 238 hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}) 239 .then((value) => { 240 // Event writing succeeded. 241 console.log(`success to write event: ${value}`); 242 }).catch((err) => { 243 // Event writing failed: The event contains invalid parameters or the event parameter verification fails. 244 console.error(`failed to write event because ${err.code}`); 245 }); 246 ``` 247 2483. Customize the application event logging function. 249 250 ```js 251 // Set the application event logging switch. 252 hiAppEvent.configure({ 253 disable: true 254 }) 255 256 // Set the maximum size of the directory that stores the event logging files. 257 hiAppEvent.configure({ 258 maxStorage: '100M' 259 }) 260 ``` 261 262#### Native 263 2641. Develop the source code. 265 266 Import the HiAppEvent module. 267 268 ```c++ 269 #include "hiappevent/hiappevent.h" 270 ``` 271 2722. Log application events. 273 274 ```c++ 275 // 1. Create an empty <strong>ParamList</strong> object. 276 ParamList list = OH_HiAppEvent_CreateParamList(); 277 278 // 2. Adds key-value pair parameters to the <strong>ParamList</strong> object. 279 // 2.1 Pass a value in the int32_t format. 280 int32_t num = 1; 281 OH_HiAppEvent_AddInt32Param(list, "int32_key", num); 282 // 2.2 Pass a value in the int32_t array format. 283 int32_t nums3[] = {1, INT32_MAX, INT32_MIN}; 284 OH_HiAppEvent_AddInt32ArrayParam(list, "int32_arr_key", nums3, sizeof(nums3) / sizeof(nums3[0])); 285 // 2.3 Pass a parameter value in the string array format. 286 char str1[] = "hello"; 287 char str2[] = "world"; 288 char* strs[] = {str1, str2}; 289 OH_HiAppEvent_AddStringArrayParam(list, "string_arr_key", strs, sizeof(strs) / sizeof(strs[0])); 290 291 // 3. Log application events. 292 int result = OH_HiAppEvent_Write("domain", "name", BEHAVIOR, list); 293 printf("HiAppEvent logging test, res=%d\n", result); 294 295 // 4. Destroy the <strong>ParamLIst</strong> object to release the memory. 296 OH_HiAppEvent_DestroyParamList(list); 297 ``` 298 2993. Customize the application event logging function. 300 301 ```c++ 302 // Disable the application event logging function. 303 OH_HiAppEvent_Configure(DISABLE, "true"); 304 305 // Set the maximum size of the directory that stores the event logging files to 100M. 306 OH_HiAppEvent_Configure(MAX_STORAGE, "100M"); 307 ``` 308 309## Repositories Involved<a name="section1371113476307"></a> 310 311[DFX Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/dfx.md) 312 313[hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README.md) 314 315[hiviewdfx\_hilog](https://gitee.com/openharmony/hiviewdfx_hilog/blob/master/README.md) 316 317<strong>hiviewdfx\_hiappevent</strong> 318 319[hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README.md) 320 321[hiviewdfx\_faultloggerd](https://gitee.com/openharmony/hiviewdfx_faultloggerd/blob/master/README.md) 322 323[hiviewdfx\_hilog\_lite](https://gitee.com/openharmony/hiviewdfx_hilog_lite/blob/master/README.md) 324 325[hiviewdfx\_hievent\_lite](https://gitee.com/openharmony/hiviewdfx_hievent_lite/blob/master/README.md) 326 327[hiviewdfx\_hiview\_lite](https://gitee.com/openharmony/hiviewdfx_hiview_lite/blob/master/README.md) 328
