From 159b7ccfdd38a4eb2ed688767b2092f80dbaf43a Mon Sep 17 00:00:00 2001 From: shawn_he Date: Fri, 23 Dec 2022 16:51:35 +0800 Subject: [PATCH] update doc Signed-off-by: shawn_he --- .../subsys-dfx-hisysevent-logging.md | 220 ++++++++-- .../subsystems/subsys-dfx-hisysevent-query.md | 390 +++++++++++++++--- 2 files changed, 512 insertions(+), 98 deletions(-) diff --git a/en/device-dev/subsystems/subsys-dfx-hisysevent-logging.md b/en/device-dev/subsystems/subsys-dfx-hisysevent-logging.md index 2bb67bf541..f03d6ef597 100644 --- a/en/device-dev/subsystems/subsys-dfx-hisysevent-logging.md +++ b/en/device-dev/subsystems/subsys-dfx-hisysevent-logging.md @@ -2,83 +2,192 @@ ## Overview -### Function +### Function Introduction HiSysEvent provides event logging APIs for OpenHarmony to record important information of key processes during system running. Besides, it supports shielding of event logging by event domain, helping you to evaluate the impact of event logging. ### Working Principles -Before logging system events, you need to complete HiSysEvent logging configuration. For details, see [HiSysEvent Logging Configuration](subsys-dfx-hisysevent-logging-config.md). +Before logging system events, you need to configure HiSysEvent logging. For details, see [HiSysEvent Logging Configuration](subsys-dfx-hisysevent-logging-config.md). ## How to Develop ### Use Cases -Use HiSysEvent logging to flush logged event data to disks. +Use HiSysEvent logging to flush logged event data to the event file. ### Available APIs -#### C++ Event Logging APIs +#### C++ Event Logging API -HiSysEvent logging is implemented using the API provided by the **HiSysEvent** class. For details, see the API Reference. +HiSysEvent logging is implemented using the API provided by the **HiSysEvent** class. For details, see the [API Header Files](/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent/include/). -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +> **NOTE** > > In OpenHarmony-3.2-Beta3, HiSysEvent logging is open for restricted use to avoid event storms. The **HiSysEvent::Write** API in Table 1 is replaced by the **HiSysEventWrite** API in Table 2. The **HiSysEvent::Write** API has been deprecated. Use the **HiSysEventWrite** API instead for HiSysEvent logging. -**Table 1** C++ event logging API (deprecated) +**Table 1** Description of the C++ event logging API (deprecated) | API | Description | -| ------------------------------------------------------------ | ---------------------- | -| template<typename... Types>
static int Write(const std::string &domain, const std::string &eventName, EventType type, Types... keyValues) | Flushes logged event data to disks.| +| ------------------------------------------------------------ | --------------------- | +| template<typename... Types> 
static int Write(const std::string &domain, const std::string &eventName, EventType type, Types... keyValues) | Flushes logged event data to the event file.| -**Table 2** C++ event logging API (in use) -| API | Description | -| ------------------------------------------------------------ | ---------------------- | -| HiSysEventWrite(domain, eventName, type, ...) | Flushes logged event data to disks.| - - **Table 3** Event types +**Table 2** Description of the C++ event logging API (in use) -| API | Description | -| --------- | ------------ | -| FAULT | Fault event| -| STATISTIC | Statistical event| -| SECURITY | Security event| -| BEHAVIOR | Behavior event| +| API | Description | +| ------------------------------------------------------------ | --------------------- | +| HiSysEventWrite(domain, eventName, type, ...) | Flushes logged event data to the event file.| + + **Table 3** Description of EventType enums + +| Event Type | Description | +| --------- | ----------- | +| FAULT | Fault event.| +| STATISTIC | Statistical event.| +| SECURITY | Security event.| +| BEHAVIOR | Behavior event.| + +#### C Event Logging API + +HiSysEvent logging is implemented using the API provided in the following table. For details, see the [API Header Files](/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent/include/). + +**Table 4** Description of the C event logging API + +| API | Description | +| ------------------------------------------------------------ | ------------------------ | +| int OH_HiSysEvent_Write(const char\* domain, const char\* name, HiSysEventEventType type, HiSysEventParam params[], size_t size); | Flushes logged event data to the event file.| + +**Table 5** Description of HiSysEventEventType enums + +| Event Type | Description | +| -------------------- | -------------- | +| HISYSEVENT_FAULT | Fault event.| +| HISYSEVENT_STATISTIC | Statistical event.| +| HISYSEVENT_SECURITY | Security event.| +| HISYSEVENT_BEHAVIOR | Behavior event.| + +**Table 6** Description of the HiSysEventParam structure + +| Attribute | Type | Description | +| --------- | -------------------- | ---------------------------------- | +| name | char name[] | Event parameter name. | +| t | HiSysEventParamType | Event parameter type. | +| v | HiSysEventParamValue | Event parameter value. | +| arraySize | size_t | Array length when the event parameter value is of the array type.| + +**Table 7** Description of HiSysEventParamType enums + +| Type | Description | +| ----------------------- | -------------------------- | +| HISYSEVENT_INVALID | Invalid event parameter. | +| HISYSEVENT_BOOL | Event parameter of the bool type. | +| HISYSEVENT_INT8 | Event parameter of the int8_t type. | +| HISYSEVENT_UINT8 | Event parameter of the uint8_t type. | +| HISYSEVENT_INT16 | Event parameter of the int16_t type. | +| HISYSEVENT_UINT16 | Event parameter of the uint16_t type. | +| HISYSEVENT_INT32 | Event parameter of the int32_t type. | +| HISYSEVENT_UINT32 | Event parameter of the uint32_t type. | +| HISYSEVENT_INT64 | Event parameter of the int64_t type. | +| HISYSEVENT_UINT64 | Event parameter of the uint64_t type. | +| HISYSEVENT_FLOAT | Event parameter of the float type. | +| HISYSEVENT_DOUBLE | Event parameter of the double type. | +| HISYSEVENT_STRING | Event parameter of the char* type. | +| HISYSEVENT_BOOL_ARRAY | Event parameter of the bool array type. | +| HISYSEVENT_INT8_ARRAY | Event parameter of the int8_t array type. | +| HISYSEVENT_UINT8_ARRAY | Event parameter of the uint8_t array type. | +| HISYSEVENT_INT16_ARRAY | Event parameter of the int16_t array type. | +| HISYSEVENT_UINT16_ARRAY | Event parameter of the uint16_t array type.| +| HISYSEVENT_INT32_ARRAY | Event parameter of the int32_t array type. | +| HISYSEVENT_UINT32_ARRAY | Event parameter of the uint32_t array type.| +| HISYSEVENT_INT64_ARRAY | Event parameter of the int64_t array type. | +| HISYSEVENT_UINT64_ARRAY | Event parameter of the uint64_t array type.| +| HISYSEVENT_FLOAT_ARRAY | Event parameter of the float array type. | +| HISYSEVENT_DOUBLE_ARRAY | Event parameter of the double array type. | +| HISYSEVENT_STRING_ARRAY | Event parameter of the char* array type. | + +**Table 8** Description of the HiSysEventParamValue union + +| Attribute| Type| Description | +| -------- | -------- | ------------------------ | +| b | bool | Event parameter value of the bool type. | +| i8 | int8_t | Event parameter value of the int8_t type. | +| ui8 | uint8_t | Event parameter value of the uint8_t type. | +| i16 | int16_t | Event parameter value of the int16_t type. | +| ui16 | uint16_t | Event parameter value of the uint16_t type.| +| i32 | int32_t | Event parameter value of the int32_t type. | +| ui32 | uint32_t | Event parameter value of the uint32_t type.| +| i64 | int64_t | Event parameter value of the int64_t type. | +| ui64 | uint64_t | Event parameter value of the uint64_t type.| +| f | float | Event parameter value of the float type. | +| d | double | Event parameter value of the double type. | +| s | char* | Event parameter value of the char* type. | +| array | void* | Event parameter value of the array type. | #### Kernel Event Logging APIs -The following table describes the kernel event logging APIs. +Kernel event logging is implemented using the APIs provided in the following table. For details, see the [API Header File](/kernel/linux/linux-5.10/include/dfx/hiview_hisysevent.h). -**Table 4** Kernel event logging APIs +**Table 9** Description of kernel event logging APIs | API | Description | -| ------------------------------------------------------------ | ------------------------------------ | -| struct hiview_hisysevent *hisysevent_create(const char *domain, const char *name, enum hisysevent_type type); | Creates a **hisysevent** object. | -| void hisysevent_destroy(struct hiview_hisysevent *event); | Destroys a **hisysevent** object. | +| ------------------------------------------------------------ | ----------------------------------- | +| struct hiview_hisysevent *hisysevent_create(const char *domain, const char *name, enum hisysevent_type type); | Creates a **hisysevent** object. | +| void hisysevent_destroy(struct hiview_hisysevent *event); | Destroys a **hisysevent** object. | | int hisysevent_put_integer(struct hiview_hisysevent *event, const char *key, long long value); | Adds event parameters of the integer type to a **hisysevent** object. | | int hisysevent_put_string(struct hiview_hisysevent *event, const char *key, const char *value); | Adds event parameters of the string type to a **hisysevent** object.| -| int hisysevent_write(struct hiview_hisysevent *event); | Flushes **hisysevent** object data to disks. | +| int hisysevent_write(struct hiview_hisysevent *event); | Flushes **hisysevent** object data to the event file. | -**Table 5** Kernel event types +**Table 10** Description of hisysevent_type enums -| API | Description | -| --------- | ------------ | -| FAULT | Fault event| -| STATISTIC | Statistical event| -| SECURITY | Security event| -| BEHAVIOR | Behavior event| +| Event Type | Description | +| --------- | ----------- | +| FAULT | Fault event.| +| STATISTIC | Statistical event.| +| SECURITY | Security event.| +| BEHAVIOR | Behavior event.| ### How to Develop #### C++ Event Logging -1. Call the event logging API wherever needed, with required event parameters passed to the API. +Call the event logging API wherever needed, with required event parameters passed to the API. ```c++ HiSysEventWrite(HiSysEvent::Domain::AAFWK, "START_APP", HiSysEvent::EventType::BEHAVIOR, "APP_NAME", "com.ohos.demo"); ``` +#### C Event Logging + +1. If you want to pass custom event parameters to the event logging API, create an event parameter object based on the event parameter type and add the object to the event parameter array. + + ```c + // Create an event parameter of the int32_t type. + HiSysEventParam param1 = { + .name = "KEY_INT32", + .t = HISYSEVENT_INT32, + .v = { .i32 = 1 }, + .arraySize = 0, + }; + + // Create an event parameter of the int32_t array type. + int32_t int32Arr[] = { 1, 2, 3 }; + HiSysEventParam param2 = { + .name = "KEY_INT32_ARR", + .t = HISYSEVENT_INT32_ARRAY, + .v = { .array = int32Arr }, + .arraySize = sizeof(int32Arr) / sizeof(int32Arr[0]), + }; + + // Add the event parameter object to the created event parameter array. + HiSysEventParam params[] = { param1, param2 }; + ``` + +2. Call the event logging API wherever needed, with required event parameters passed to the API. + + ```c + OH_HiSysEvent_Write("TEST_DOMAIN", "TEST_NAME", HISYSEVENT_BEHAVIOR, params, sizeof(params) / sizeof(params[0])); + ``` + #### Kernel Event Logging 1. Create a **hisysevent** object based on the specified event domain, event name, and event type. @@ -151,7 +260,7 @@ Assume that a service module needs to trigger event logging during application s external_deps = [ "hisysevent_native:libhisysevent" ] ``` -2. In the application startup function **StartAbility()** of the service module, call the event logging API with the event parameters passed in. +2. In the application startup function **StartAbility()** of the service module, call the event logging API with event parameters passed in. ```c++ #include "hisysevent.h" @@ -164,6 +273,37 @@ Assume that a service module needs to trigger event logging during application s } ``` +#### C Event Logging + +Assume that a service module needs to trigger event logging during application startup to record the application startup event and application bundle name. The following is the complete sample code: + +1. Add the HiSysEvent component dependency to the **BUILD.gn** file of the service module. + + ```c++ + external_deps = [ "hisysevent_native:libhisysevent" ] + ``` + +2. In the application startup function **StartAbility()** of the service module, call the event logging API with event parameters passed in. + + ```c + #include "hisysevent_c.h" + + int StartAbility() + { + ... // Other service logic + char packageName[] = "com.ohos.demo"; + HiSysEventParam param = { + .name = "APP_NAME", + .t = HISYSEVENT_STRING, + .v = { .s = packageName }, + .arraySize = 0, + }; + HiSysEventParam params[] = { param }; + int ret = OH_HiSysEvent_Write("AAFWK", "START_APP", HISYSEVENT_BEHAVIOR, params, sizeof(params) / sizeof(params[0])); + ... // Other service logic + } + ``` + #### Kernel Event Logging Assume that the kernel service module needs to trigger event logging during device startup to record the device startup event. The following is the complete sample code: @@ -200,11 +340,10 @@ Assume that the kernel service module needs to trigger event logging during devi } ``` -#### Shielding of Event Logging by Event Domain +#### Shielding of Event Logging by Event Domain - If you want to shield event logging for the **AAFWK** and **POWER** domains in a **.cpp** file, define the **DOMAIN_MASKS** macro before including the **hisysevent.h** header file to the **.cpp** file. ```c++ - #define DOMAIN_MASKS "AAFWK|POWER" #include "hisysevent.h" @@ -212,14 +351,13 @@ Assume that the kernel service module needs to trigger event logging during devi HiSysEventWrite(OHOS:HiviewDFX::HiSysEvent::Domain::AAFWK, "JS_ERROR", OHOS:HiviewDFX::HiSysEvent::EventType::FAULT, "MODULE", "com.ohos.module"); // HiSysEvent logging is not performed. ... // Other service logic HiSysEventWrite(OHOS:HiviewDFX::HiSysEvent::Domain::POWER, "POWER_RUNNINGLOCK", OHOS:HiviewDFX::HiSysEvent::EventType::FAULT, "NAME", "com.ohos.module"); // HiSysEvent logging is not performed. - ``` - If you want to shield event logging for the **AAFWK** and **POWER** domains of the entire service module, define the **DOMAIN_MASKS** macro as follows in the **BUILG.gn** file of the service module. ```gn config("module_a") { - ... // Other configuration items - cflags_cc += ["-DDOMAIN_MASKS=\"AAFWK|POWER\""] + ... // Other configuration items + cflags_cc += ["-DDOMAIN_MASKS=\"AAFWK|POWER\""] } ``` diff --git a/en/device-dev/subsystems/subsys-dfx-hisysevent-query.md b/en/device-dev/subsystems/subsys-dfx-hisysevent-query.md index 66cd39343e..2f5cd08ffa 100644 --- a/en/device-dev/subsystems/subsys-dfx-hisysevent-query.md +++ b/en/device-dev/subsystems/subsys-dfx-hisysevent-query.md @@ -6,106 +6,382 @@ HiSysEvent allows you to query system events by specifying search criteria. For example, for a power consumption module, you can query required system events for analysis. -## Development Guidelines - +## How to Develop ### Available APIs -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** +#### C++ Event Query API + +HiSysEvent query is implemented using the API provided by the **HiSysEventManager** class. For details, see the [API Header Files](/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/). + +> **NOTE** > -> For details about the **HiSysEventRecord** argument in the **OnQuery()** method of **HiSysEventQueryCallback**, see Table 5 in [HiSysEvent Listening](subsys-dfx-hisysevent-listening.md). +> For details about **HiSysEventRecord** in the **OnQuery()** API of **HiSysEventQueryCallback**, see Table 5 in [HiSysEvent Listening](subsys-dfx-hisysevent-listening.md). -**Table 1** Description of the HiSysEvent query API + **Table 1** Description of the HiSysEvent query API -| API | Description | -| --- | ----------- | -| int32_t HiSysEventManager::Query(struct QueryArg& arg, std::vector<QueryRule>& rules, std::shared_ptr<HiSysEventQueryCallback> callback) | Queries system events by specifying search criteria such as the time segment, event domain, and event name.
Input arguments:
- **arg**: event query parameter.
- **rules**: rules for event filtering.
- **callback**: callback object for event query.
Return value:
- **0**: Query is successful.
- A negative value: Query has failed.| +| API| Description| +| -------- | -------- | +| int32_t Query(struct QueryArg& arg,
std::vector<QueryRule>& rules,
std::shared_ptr<HiSysEventQueryCallback> callback) | Queries system events by search criteria such as the time segment, event domain, and event name.
Input arguments:
- **arg**: event query parameter.
- **rules**: rules for event filtering.
- **callback**: callback object for event query.
Return value:
- **0**: Query is successful.
- A negative value: Query has failed.| -**Table 2** Description of QueryArg + **Table 2** Description of QueryArg objects -| Attribute | Description | -| --------- | ----------- | -| beginTime | Start time, in the **long long int** format.| -| endTime | End time, in the **long long int** format.| -| maxEvents | Maximum number of returned events, in the **int** format.| +| Attribute| Type| Description| +| -------- | -------- | -------- | +| beginTime | long long | Start time for query. The value is a Unix timestamp, in milliseconds.| +| endTime | long long | End time for query. The value is a Unix timestamp, in milliseconds.| +| maxEvents | int | Maximum number of returned events.| -**Table 3** Description of QueryRule + **Table 3** Description of QueryRule objects | API| Description| | -------- | -------- | -| QueryRule(const std::string& domain, const std::vector<std::string>& eventList) | Constructor used to create a **QueryRule** object.
Input arguments:
- **domain**: domain to which the event of the **QueryRule** object belongs, in the string format. By default, an empty string indicates that the domain is successfully matched.
- **eventList**: event name list, in the **std::vector<std::string>** format. By default, an empty string indicates that the event names on the list are successfully matched.| +| QueryRule(const std::string& domain,
const std::vector<std::string>& eventList) | Constructor used to create a **QueryRule** object.
Input arguments:
- **domain**: domain to which the event of the **QueryRule** object belongs, in the string format. By default, an empty string indicates that the domain is successfully matched.
**eventList**: event name list, in the **std::vector<std::string>** format. By default, an empty string indicates that the event names on the list are successfully matched.| -**Table 4** Description of HiSysEventQueryCallback + **Table 4** Description of HiSysEventQueryCallback objects | API| Description| | -------- | -------- | -| void HiSysEventQueryCallback::OnQuery(std::shared_ptr<std::vector<HiSysEventRecord>> sysEvents) | Callback object for event query.
Input arguments:
- **sysEvents**: event list.
Return value:
None.| -| void HiSysEventQueryCallback::OnComplete(int32_t reason, int32_t total) | Callback object for completion of event query.
Input arguments:
- **reason**: reason for completion of event query. The default value is **0**.
- **total**: total number of events returned in this query.
Return value:
None.| +| void HiSysEventQueryCallback::OnQuery(std::shared_ptr<std::vector<HiSysEventRecord>> sysEvents) | Callback object for event query.
Input arguments:
- **sysEvents**: event list.| +| void HiSysEventQueryCallback::OnComplete(int32_t reason, int32_t total) | Callback object for completion of event query.
Input arguments:
- **reason**: reason for completion of event query. The value **0** indicates that the query is normal, and any other value indicates that the query has failed.
- **total**: total number of events returned in this query.| + +#### C Event Query API + +HiSysEvent query is implemented using the API provided in the following table. For details, see the [API Header Files](/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/). + + **Table 5** Description of the HiSysEvent query API + +| API | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| int OH_HiSysEvent_Query(const HiSysEventQueryArg& arg, HiSysEventQueryRule rules[], size_t ruleSize, HiSysEventQueryCallback& callback); | Queries system events by search criteria such as the time segment, event domain, event name, and event parameter.
Input arguments:
- **arg**: event query parameter.
- **rules**: rules for event filtering.
- **ruleSize**: number of event filtering rules.
- **callback**: callback object for event query.
Return value:
- **0**: Query is successful.
- A negative value: Query has failed.| + + **Table 6** Description of the HiSysEventQueryArg structure + +| Attribute | Type| Description | +| --------- | -------- | ---------------------------------------------------- | +| beginTime | int64_t | Start time for query. The value is a Unix timestamp, in milliseconds.| +| endTime | int64_t | End time for query. The value is a Unix timestamp, in milliseconds.| +| maxEvents | int32_t | Maximum number of returned events. | + +**Table 7** Description of the HiSysEventQueryRule structure + +| Attribute | Type | Description | +| ------------- | --------- | ---------------------------------- | +| domain | char[] | Event domain. | +| eventList | char\[][] | Event name list. | +| eventListSize | size_t | Size of the event name list. | +| condition | char* | Custom event parameter conditions for the query.| + +The **condition** parameter must be in the specified JSON string format. For example: + +```json +{ + "version":"V1", + "condition":{ + "and":[ + {"param":"type_","op":">","value":0}, + {"param":"uid_","op":"=","value":1201} + ], + "or":[ + {"param":"NAME","op":"=","value":"SysEventService"}, + {"param":"NAME","op":"=","value":"SysEventSource"} + ] + } +} +``` + +- The **version** field is mandatory, indicating the supported version of the input condition. Currently, only **V1** is supported. +- The **condition** field is mandatory, indicating the input condition. + - The **and** field is optional, indicating the AND relationship between conditions. + - The **or** field is optional, indicating the OR relationship between conditions. + - The **param** field is mandatory, indicating the parameter name for condition matching. The value must be a string. + - The **op** field is mandatory, indicating the parameter comparison operator for condition matching. The value must be a string. Supported comparison operators include the following: =, >, <, >=, and <=. + - The **value** field is mandatory, indicating the parameter value for condition matching. The value must be a string or an integer. + +**Table 8** Description of the HiSysEventQueryCallback structure + +| Attribute | Type | Description | +| ---------- | -------------------------------------------------- | ------------------------------------------------------------ | +| OnQuery | void (*)(HiSysEventRecord records[], size_t size); | Callback object for event query.
Input arguments:
- **records**: event list.
- **size**: size of the event list.| +| OnComplete | void (*)(int32_t reason, int32_t total); | Callback object for completion of event query.
Input arguments:
- **reason**: reason for completion of event query. The value **0** indicates that the query is normal, and any other value indicates that the query has failed.
- **total**: total number of events returned in this query.| + +**Table 9** Description of the HiSysEventRecord event structure + +| Attribute | Type | Description | +| --------- | ------------------- | -------------------------- | +| domain | char[] | Event domain. | +| eventName | char\[] | Event name. | +| type | HiSysEventEventType | Event type. | +| time | uint64_t | Event timestamp. | +| tz | char\[] | Event time zone. | +| pid | int64_t | Process ID of the event. | +| tid | int64_t | Thread ID of the event. | +| uid | int64_t | User ID of the event. | +| traceId | uint64_t | Distributed call chain trace ID of the event. | +| spandId | uint64_t | Span ID for the distributed call chain trace of the event. | +| pspanId | uint64_t | Parent span ID for the distributed call chain trace of the event.| +| traceFlag | int | Distributed call chain trace flag of the event. | +| level | char* | Event level. | +| tag | char* | Event tag. | +| jsonStr | char* | Event content. | + +**Table 10** Description of HiSysEventRecord APIs + +| API | | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| void OH_HiSysEvent_GetParamNames(const HiSysEventRecord& record, char*** params, size_t& len); | Obtains all parameter names of an event.
Input arguments:
- **record**: event structure.
- **params**: parameter name array.
- **len**: size of the parameter name array.| +| int OH_HiSysEvent_GetParamInt64Value(const HiSysEventRecord& record, const char* name, int64_t& value); | Parses the parameter value in the event to an int64_t value and assigns the value to **value**.
Input arguments:
- **record**: event structure.
- **name**: parameter name.
- **value**: parameter value of the int64_t type.| +| int OH_HiSysEvent_GetParamUint64Value(const HiSysEventRecord& record, const char* name, uint64_t& value); | Parses the parameter value in the event to an uint64_t value and assigns the value to **value**.
Input arguments:
- **record**: event structure.
- **name**: parameter name.
- **value**: parameter value of the uint64_t type.| +| int OH_HiSysEvent_GetParamDoubleValue(const HiSysEventRecord& record, const char* name, double& value); | Parses the parameter value in the event to a double value and assigns the value to **value**.
Input arguments:
- **record**: event structure.
- **name**: parameter name.
- **value**: parameter value of the double type.| +| int OH_HiSysEvent_GetParamStringValue(const HiSysEventRecord& record, const char* name, char** value); | Parses the parameter value in the event to a char array value and assigns the value to **value**. You need to release the memory manually after usage.
Input arguments:
- **record**: event structure.
- **name**: parameter name.
- **value**: char\* reference.| +| int OH_HiSysEvent_GetParamInt64Values(const HiSysEventRecord& record, const char* name, int64_t** value, size_t& len); | Parses the parameter value in the event to a int64_t array value and assigns the value to **value**. You need to release the memory manually after usage.
Input arguments:
- **record**: event structure.
- **name**: parameter name.
- **value**: int64_t\* reference.
- **len**: array size.| +| int OH_HiSysEvent_GetParamUint64Values(const HiSysEventRecord& record, const char* name, uint64_t** value, size_t& len); | Parses the parameter value in the event to a uint64_t array value and assigns the value to **value**. You need to release the memory manually after usage.
Input arguments:
- **record**: event structure.
- **name**: parameter name.
- **value**: uint64_t\* reference.
- **len**: array size.| +| int OH_HiSysEvent_GetParamDoubleValues(const HiSysEventRecord& record, const char* name, double** value, size_t& len); | Parses the parameter value in the event to a double array value and assigns the value to **value**. You need to release the memory manually after usage.
Input arguments:
- **record**: event structure.
- **name**: parameter name.
- **value**: double\* reference.
- **len**: array size.| +| int OH_HiSysEvent_GetParamStringValues(const HiSysEventRecord& record, const char* name, char*** value, size_t& len); | Parses the parameter value in the event to a char* array value and assigns the value to **value**. You need to release the memory manually after usage.
Input arguments:
- **record**: event structure.
- **name**: parameter name.
- **value**: char\*\* reference.
- **len**: array size.| + +The return values of the HiSysEventRecord APIs are described as follows: + +- **0**: The parsing is successful. +- -**1**: The event fails to be initialized. +- -**2**: The parameter name does not exist. +- -**3**: The type of the parameter value to be parsed does not match the type of the input parameter value. ### How to Develop -**C++** +#### C++ HiSysEvent Query API -1. Develop the source code. - Import the corresponding header file: +1. Import the corresponding header file: - ``` + ```c++ #include "hisysevent_manager.h" ``` - Implement the callback API. +2. Implement the callback API. - ``` - void HiSysEventQueryCallback::OnQuery(std::shared_ptr> sysEvents) - void HiSysEventQueryCallback::OnComplete(int32_t reason, int32_t total) + ```c++ + class TestQueryCallback : public HiSysEventQueryCallback { + public: + void OnQuery(std::shared_ptr> sysEvents) override + { + if (sysEvents == nullptr) { + return; + } + for_each((*sysEvents).cbegin(), (*sysEvents).cend(), [](const HiSysEventRecord& event) { + std::cout << event.AsJson() << std::endl; + }); + } + + void OnComplete(int32_t reason, int32_t total) override + { + std::cout << "Query completed" << std::endl; + return; + } + }; ``` - Call the query API in the corresponding service logic. +3. Call the query API while passing in the query parameter, rule, and callback object. + ```c++ + // Create a query parameter object. + long long startTime = 0; + long long endTime = 1668245644000; //2022-11-12 09:34:04 + int queryCount = 10; + QueryArg arg(startTime, endTime, queryCount); + + // Create a query rule object. + QueryRule rule("HIVIEWDFX", { "PLUGIN_LOAD" }); + std::vector queryRules = { rule }; + + // Create a query callback object. + auto queryCallback = std::make_shared(); + + // Call the query API. + HiSysEventManager::Query(arg, queryRules, queryCallback); ``` - HiSysEventManager::Query(struct QueryArg& queryArg, - std::vector& queryRules, std::shared_ptr queryCallBack) - ``` - In this example, you'll query all system events. +#### C HiSysEvent Query API + +1. Import the corresponding header file: + ```c++ + #include "hisysevent_manager_c.h" ``` - #include "hisysevent_manager.h" - #include - namespace OHOS { - namespace HiviewDFX { - // Implement the query callback API. - void HiSysEventToolQuery::OnQuery(std::shared_ptr> sysEvents) +2. Implement the callback API. + + ```c++ + void OnQueryTest(HiSysEventRecord records[], size_t size) { - if (sysEvents == nullptr) { - return; + for (size_t i = 0; i < size; i++) { + printf("OnQuery: event=%s", records[i].jsonStr); } - for_each((*sysEvents).cbegin(), (*sysEvents).cend(), [](const HiSysEventRecord& event) { - std::cout << event.AsJson() << std::endl; - }); } - - void HiSysEventToolQuery::OnComplete(int32_t reason, int32_t total) + + void OnCompleteTest(int32_t reason, int32_t total) { - return; + printf("OnCompleted, res=%d, total=%d\n", reason, total); } - } // namespace HiviewDFX - } // namespace OHOS - - // Call the query callback API to obtain system events. - auto queryCallBack = std::make_shared(); - struct QueryArg args(clientCmdArg.beginTime, clientCmdArg.endTime, clientCmdArg.maxEvents); - std::vector rules; - HiSysEventManager::QueryHiSysEvent(args, rules, queryCallBack); ``` -2. Modify the **BUILD.gn** file. - In the **BUILD.gn** file, add the **libhisysevent** and **libhisyseventmanager** libraries that depend on the **hisysevent_native** component. - +3. Call the query API while passing in the query parameter, rule, and callback object. + + ```c++ + // Create a query parameter object. + HiSysEventQueryArg arg; + arg.beginTime = 0; + arg.endTime = 1668245644000; //2022-11-12 09:34:04 + arg.maxEvents = 10; + + // Create a query rule object. + constexpr char TEST_DOMAIN[] = "HIVIEWDFX"; + constexpr char TEST_NAME[] = "PLUGIN_LOAD"; + HiSysEventQueryRule rule; + (void)strcpy_s(rule.domain, strlen(TEST_DOMAIN) + 1, TEST_DOMAIN); + (void)strcpy_s(rule.eventList[0], strlen(TEST_NAME) + 1, TEST_NAME); + rule.eventListSize = 1; + rule.condition = nullptr; + HiSysEventQueryRule rules[] = { rule }; + + // Create a query callback object. + HiSysEventQueryCallback callback; + callback.OnQuery = OnQueryTest; + callback.OnComplete = OnCompleteTest; + + // Call the query API. + OH_HiSysEvent_Query(arg, rules, sizeof(rules) / sizeof(HiSysEventQueryRule), callback); ``` + +### Development Example + +#### C++ HiSysEvent Query + +Assume that you need to query all **PLUGIN_LOAD** events that are generated for the **HIVIEWDFX** domain until the current time on a service module. The development procedure is as follows: + +1. Add the **libhisysevent** and **libhisyseventmanager** dependencies of the **hisysevent_native** component to **BUILD.gn** of the service module. + + ```c++ external_deps = [ "hisysevent_native:libhisysevent", "hisysevent_native:libhisyseventmanager", ] ``` + +2. Call the query API in the **TestQuery()** function of the service module. + + ```c++ + #include "hisysevent_manager.h" + #include + #include + + using namespace OHOS::HiviewDFX; + + class TestQueryCallback : public HiSysEventQueryCallback { + public: + void OnQuery(std::shared_ptr> sysEvents) override + { + if (sysEvents == nullptr) { + return; + } + for_each((*sysEvents).cbegin(), (*sysEvents).cend(), [](const HiSysEventRecord& event) { + std::cout << event.AsJson() << std::endl; + }); + } + + void OnComplete(int32_t reason, int32_t total) override + { + std::cout << "Query completed" << std::endl; + return; + } + }; + + int64_t GetMilliseconds() + { + auto now = std::chrono::system_clock::now(); + auto millisecs = std::chrono::duration_cast(now.time_since_epoch()); + return millisecs.count(); + } + + void TestQuery() + { + // Create a query parameter object. + long long startTime = 0; + long long endTime = GetMilliseconds(); + int maxEvents = 100; + QueryArg arg(startTime, endTime, maxEvents); + + // Create a query rule object. + QueryRule rule("HIVIEWDFX", { "PLUGIN_LOAD" }); + std::vector queryRules = { rule }; + + // Create a query callback object. + auto queryCallback = std::make_shared(); + + // Call the query API. + int ret = HiSysEventManager::Query(arg, queryRules, queryCallback); + } + ``` + +#### C HiSysEvent Query + +Assume that you need to query all **PLUGIN_LOAD** events that are generated for the **HIVIEWDFX** domain until the current time on a service module. The development procedure is as follows: + +1. Add the **libhisyseventmanager** dependency of the **hisysevent_native** component to the **BUILD.gn** file of the service module. + + ```c++ + external_deps = [ "hisysevent_native:libhisyseventmanager" ] + + // for strcpy_s + deps = [ "//third_party/bounds_checking_function:libsec_shared" ] + ``` + +2. Call the query API in the **TestQuery()** function of the service module. + + ```c++ + #include "hisysevent_manager_c.h" + #include + #include + + void OnQueryTest(HiSysEventRecord records[], size_t size) + { + for (size_t i = 0; i < size; i++) { + printf("OnQuery: event=%s", records[i].jsonStr); + } + } + + void OnCompleteTest(int32_t reason, int32_t total) + { + printf("OnCompleted, res=%d, total=%d\n", reason, total); + } + + int64_t GetMilliseconds() + { + return time(NULL); + } + + void TestQuery() + { + // Create a query parameter object. + HiSysEventQueryArg arg; + arg.beginTime = 0; + arg.endTime = GetMilliseconds(); + arg.maxEvents = 100; + + // Create a query rule object. + constexpr char TEST_DOMAIN[] = "HIVIEWDFX"; + constexpr char TEST_NAME[] = "PLUGIN_LOAD"; + HiSysEventQueryRule rule; + (void)strcpy_s(rule.domain, strlen(TEST_DOMAIN) + 1, TEST_DOMAIN); + (void)strcpy_s(rule.eventList[0], strlen(TEST_NAME) + 1, TEST_NAME); + rule.eventListSize = 1; + rule.condition = nullptr; + HiSysEventQueryRule rules[] = { rule }; + + // Create a query callback object. + HiSysEventQueryCallback callback; + callback.OnQuery = OnQueryTest; + callback.OnComplete = OnCompleteTest; + + // Call the query API. + int ret = OH_HiSysEvent_Query(arg, rules, sizeof(rules) / sizeof(HiSysEventQueryRule), callback); + } + ``` -- GitLab