8 Star 7 Fork 32

OpenHarmony / hiviewdfx_hiappevent

Create your Gitee Account
Explore and code with more than 8 million developers,Free private repositories !:)
Sign up
Clone or Download
contribute
Sync branch
Cancel
Notice: Creating folder will generate an empty file .keep, because not support in Git
Loading...
README.md

HiAppEvent

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

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.

    import hiAppEvent from '@ohos.hiAppEvent'
  2. Log application events.

    // 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.

    // 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.

    #include "hiappevent/hiappevent.h"
  2. Log application events.

    // 1. Create an empty <strong>ParamList</strong> object.
    ParamList list = OH_HiAppEvent_CreateParamList();
    
    // 2. Adds key-value pair parameters to the <strong>ParamList</strong> 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 <strong>ParamLIst</strong> object to release the memory.
    OH_HiAppEvent_DestroyParamList(list);
  3. Customize the application event logging function.

    // 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

hiviewdfx_hiview

hiviewdfx_hilog

hiviewdfx_hiappevent

hiviewdfx_hisysevent

hiviewdfx_faultloggerd

hiviewdfx_hilog_lite

hiviewdfx_hievent_lite

hiviewdfx_hiview_lite

About

Application event logging | 应用事件记录接口及框架 expand collapse
C++ and 3 more languages
Apache-2.0
Cancel

Releases

No release

OpenHarmony

Contributors

All

Activities

Load More
can not load any more
1
https://git.oschina.net/openharmony/hiviewdfx_hiappevent.git
git@git.oschina.net:openharmony/hiviewdfx_hiappevent.git
openharmony
hiviewdfx_hiappevent
hiviewdfx_hiappevent
master

Search