# HiAppEvent - [Introduction](#section11660541593) - [Directory Structure](#section161941989596) - [Compilation and Building](#section137768191623) - [Usage](#section1312121216216) - [Available APIs](#section1551164914237) - [How to Use](#section129654513264) - [Repositories Involved](#section1371113476307) ## Introduction HiAppEvent 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. Figure 1 HiAppEvent architecture ![](figures/HiAppEvent-architecture.png "HiAppEvent-architecture") ## Directory Structure ``` /base/hiviewdfx/hiappevent # HiAppEvent source code ├── frameworks # Framework code │ └── native # Native implementation code of logging APIs ├── interfaces # External APIs │ └── js # JS APIs │ └── innerkits # JS API implementation code │ └── napi # JS APIs implemented based on NAPI ├── test # Test cases ``` ## Compilation and Building Use Clang 8.0.0 and C++11 or higher. ## Usage ### Available APIs #### JS APIs Table 1 JS APIs for event logging

Module

API

Description

hiAppEvent

write(string eventName, EventType type, object keyValues, AsyncCallback<void> callback): void

Logs application events in asynchronous mode. This function uses an asynchronous callback to return the result.

Input arguments:

  • eventName: indicates the event name.
  • type: indicates the event type.
  • keyValues: indicates the key-value pairs of event parameters. The value is in the JSON format.
  • callback: indicates the callback used to process the received return value. The value 0 indicates that the event parameter verification is successful, and the event will be written to the event file asynchronously. 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. A value smaller than 0 indicates that the event parameter verification fails, and the event will not be written to the event file asynchronously.

hiAppEvent

write(string eventName, EventType type, object keyValues): Promise<void>

Logs application events in asynchronous mode. This function uses a promise to return the result.

Input arguments: same as those in the preceding function
Table 2 JS event types (EventType) | Type| Description| | --------- | -------------- | | FAULT | Fault event| | STATISTIC | Statistical event| | SECURITY | Security event| | BEHAVIOR | Behavior event| Table 3 JS APIs for event logging configuration
Module API Description
hiAppEvent configure(config: ConfigOption): boolean Sets the configuration options for application event logging.
Input arguments:
  • config: indicates configuration options for application event logging.
Return value: The value true indicates the operation is successful, and the value false indicates the opposite.
Table 4 JS logging configuration options (ConfigOption) | Name| Type| Mandatory| Description| | ---------- | ------- | ---- | ------------------------------------------------------------ | | disable | boolean | No| Application event logging switch. The value true means to disable the application event logging function, and the value false means the opposite.| | 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 directory will be deleted to free up space.| Table 5 JS predefined event name constants (Event) | Constant| Type| Description| | ------------------------- | ------ | -------------------- | | USER_LOGIN | string | User login event.| | USER_LOGOUT | string | User logout event.| | DISTRIBUTED\_SERVICE\_START| string | Distributed service startup event.| Table 6 JS predefined parameter name constants (Param) | Constant| Type| Description| | ------------------------------- | ------ | ------------------ | | USER_ID | string | Custom user ID.| | DISTRIBUTED\_SERVICE\_NAME| string | Distributed service name.| | DISTRIBUTED\_SERVICE\_INSTANCE\_ID| string | Distributed service instance ID.| #### Native APIs Table 1 Native APIs for event logging
API Return Value Description
OH_HiAppEvent_Write(const char* domain, const char* name, enum EventType type, const ParamList list) int Implements logging of application events.
Input arguments:
  • domain: indicates the event domain.
  • name: indicates the event name.
  • type: indicates the event type.
  • list: indicates the event parameter list. It is actually a pointer to the the linked list head node — ParamListNode*. Each parameter in the list consists of a parameter name and a parameter value.
Return value: error code in the int format.
Table 2 Native APIs for constructing ParamList | API| Return Value| Description| | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | | OH\_HiAppEvent\_CreateParamList()| ParamList | Creates a ParamList node. A pointer to the created node is returned.| | OH_HiAppEvent_DestroyParamList(ParamList list) | void | Deletes ParamList nodes one by one from the head node and releases the memory.| | OH_HiAppEvent_AddBoolParam(ParamList list, const char* name, bool boolean) | ParamList | Creates a parameter node of the bool type and adds it to ParamList.| | OH_HiAppEvent_AddBoolArrayParam(ParamList list, const char* name, const bool* booleans, int arrSize) | ParamList | Creates a parameter node of the bool array type and adds it to ParamList.| | OH_HiAppEvent_AddInt8Param(ParamList list, const char* name, int8_t num) | ParamList | Creates a parameter node of the int8_t type and adds it to ParamList.| | OH_HiAppEvent_AddInt8ArrayParam(ParamList list, const char* name, const int8_t* nums, int arrSize) | ParamList | Creates a parameter node of the int8_t array type and adds it to ParamList.| | OH_HiAppEvent_AddInt16Param(ParamList list, const char* name, int16_t num) | ParamList | Creates a parameter node of the int16_t type and adds it to ParamList.| | OH_HiAppEvent_AddInt16ArrayParam(ParamList list, const char* name, const int16_t* nums, int arrSize) | ParamList | Creates a parameter node of the int16_t array type and adds it to ParamList.| | OH_HiAppEvent_AddInt32Param(ParamList list, const char* name, int32_t num) | ParamList | Creates a parameter node of the int32_t type and adds it to ParamList.| | OH_HiAppEvent_AddInt32ArrayParam(ParamList list, const char* name, const int32_t* nums, int arrSize) | ParamList | Creates a parameter node of the int32_t array type and adds it to ParamList.| | OH_HiAppEvent_AddInt64Param(ParamList list, const char* name, int64_t num) | ParamList | Creates a parameter node of the int64_t type and adds it to ParamList.| | OH_HiAppEvent_AddInt64ArrayParam(ParamList list, const char* name, const int64_t* nums, int arrSize) | ParamList | Creates a parameter node of the int64_t array type and adds the node to ParamList.| | OH_HiAppEvent_AddFloatParam(ParamList list, const char* name, float num) | ParamList | Creates a parameter node of the float type and adds it to ParamList.| | OH_HiAppEvent_AddFloatArrayParam(ParamList list, const char* name, const float* nums, int arrSize) | ParamList | Creates a parameter node of the float array type and adds it to ParamList.| | OH_HiAppEvent_AddDoubleParam(ParamList list, const char* name, double num) | ParamList | Creates a parameter node of the double type and adds it to ParamList.| | OH_HiAppEvent_AddDoubleArrayParam(ParamList list, const char* name, const double* nums, int arrSize) | ParamList | Creates a parameter node of the double array type and adds it to ParamList.| | OH_HiAppEvent_AddStringParam(ParamList list, const char* name, const char* str) | ParamList | Creates a parameter node of the char* type and adds it to ParamList.| | OH_HiAppEvent_AddStringArrayParam(ParamList list, const char* name, const char * const *strs, int arrSize) | ParamList | Creates a parameter node of the char* array type and adds it to ParamList.| Table 3 Native APIs for event logging configuration
API Return Value Description
OH_HiAppEvent_Configure(const char* name, const char* value) bool Sets the configuration options for application event logging.
Input arguments:
  • name: indicates the name of a configuration item. You can pass a predefined configuration item constant.
  • value: indicates the value of the configuration item.
Return value: The value true indicates the operation is successful, and the value false indicates the opposite.
Table 4 Predefined configuration item constants | Constant| Type| Description| | ----------- | ------------ | ------------------------------------------------------------ | | DISABLE | const char[] | Sets the application event logging switch. The value true means to disable the application event logging function, and the value false means the opposite.| | MAX_STORAGE | const char[] | Specifies the maximum size of the event file storage directory. The default value is 10M.| Table 5 Predefined event name constants | Constant| Type| Description| | ------------------------------- | ------------ | ------------------------ | | EVENT_USER_LOGIN | const char[] | Name of the user login event.| | EVENT_USER_LOGOUT | const char[] | Name of the user logout event.| | EVENT_DISTRIBUTED_SERVICE_START | const char[] | Name of the distributed service startup event.| Table 6 Predefined parameter name constants | Constant| Type| Description| | ------------------------------------- | ------------ | ------------------ | | PARAM_USER_ID | const char[] | Custom user ID.| | PARAM_DISTRIBUTED_SERVICE_NAME | const char[] | Distributed service name.| | PARAM_DISTRIBUTED_SERVICE_INSTANCE_ID | const char[] | Distributed service instance ID.| ### How to Use #### JS 1. Develop the source code. Import the HiAppEvent module. ```js import hiAppEvent from '@ohos.hiAppEvent' ``` 2. Log application events. ```js // Callback mode hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}, (err, value) => { if (err) { // Event writing failed: The event contains invalid parameters or the event parameter verification fails. console.error(`failed to write event because ${err.code}`); return; } // Event writing succeeded. console.log(`success to write event: ${value}`); }); // Promise mode hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}) .then((value) => { // Event writing succeeded. console.log(`success to write event: ${value}`); }).catch((err) => { // Event writing failed: The event contains invalid parameters or the event parameter verification fails. console.error(`failed to write event because ${err.code}`); }); ``` 3. Customize the application event logging function. ```js // Set the application event logging switch. hiAppEvent.configure({ disable: true }) // Set the maximum size of the directory that stores the event logging files. hiAppEvent.configure({ maxStorage: '100M' }) ``` #### Native 1. Develop the source code. Import the HiAppEvent module. ```c++ #include "hiappevent/hiappevent.h" ``` 2. Log application events. ```c++ // 1. Create an empty ParamList object. ParamList list = OH_HiAppEvent_CreateParamList(); // 2. Adds key-value pair parameters to the ParamList object. // 2.1 Pass a value in the int32_t format. int32_t num = 1; OH_HiAppEvent_AddInt32Param(list, "int32_key", num); // 2.2 Pass a value in the int32_t array format. int32_t nums3[] = {1, INT32_MAX, INT32_MIN}; OH_HiAppEvent_AddInt32ArrayParam(list, "int32_arr_key", nums3, sizeof(nums3) / sizeof(nums3[0])); // 2.3 Pass a parameter value in the string array format. char str1[] = "hello"; char str2[] = "world"; char* strs[] = {str1, str2}; OH_HiAppEvent_AddStringArrayParam(list, "string_arr_key", strs, sizeof(strs) / sizeof(strs[0])); // 3. Log application events. int result = OH_HiAppEvent_Write("domain", "name", BEHAVIOR, list); printf("HiAppEvent logging test, res=%d\n", result); // 4. Destroy the ParamLIst object to release the memory. OH_HiAppEvent_DestroyParamList(list); ``` 3. Customize the application event logging function. ```c++ // Disable the application event logging function. OH_HiAppEvent_Configure(DISABLE, "true"); // Set the maximum size of the directory that stores the event logging files to 100M. OH_HiAppEvent_Configure(MAX_STORAGE, "100M"); ``` ## Repositories Involved [DFX Subsystem](https://gitee.com/openharmony/docs/blob/master/en/readme/dfx.md) [hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README.md) [hiviewdfx\_hilog](https://gitee.com/openharmony/hiviewdfx_hilog/blob/master/README.md) hiviewdfx\_hiappevent [hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README.md) [hiviewdfx\_faultloggerd](https://gitee.com/openharmony/hiviewdfx_faultloggerd/blob/master/README.md) [hiviewdfx\_hilog\_lite](https://gitee.com/openharmony/hiviewdfx_hilog_lite/blob/master/README.md) [hiviewdfx\_hievent\_lite](https://gitee.com/openharmony/hiviewdfx_hievent_lite/blob/master/README.md) [hiviewdfx\_hiview\_lite](https://gitee.com/openharmony/hiviewdfx_hiview_lite/blob/master/README.md)