From 0641092baa902d3bfb659f1b63abcd4b32e3015c Mon Sep 17 00:00:00 2001 From: lyj_love_code Date: Sat, 12 Nov 2022 14:52:04 +0800 Subject: [PATCH] add write and query interface for c Signed-off-by: lyj_love_code --- .../subsys-dfx-hisysevent-logging.md | 216 ++++++++-- .../subsystems/subsys-dfx-hisysevent-query.md | 377 +++++++++++++++--- 2 files changed, 503 insertions(+), 90 deletions(-) diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging.md b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging.md index 4c8ed67988..8c871f3957 100644 --- a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging.md +++ b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging.md @@ -4,82 +4,191 @@ ### 功能简介 -HiSysEvent打点提供了事件埋点功能，开发者可以通过在关键路径埋点来记录系统在运行过程中的重要信息。同时，HiSysEvent打点也提供了以事件领域为单位的HiSysEvent打点屏蔽机制，方便开发者评估及调试HiSysEvent打点操作的影响。 +HiSysEvent打点提供了事件打点功能，开发者可以通过在关键路径打点来记录系统在运行过程中的重要信息。同时，HiSysEvent打点也提供了以事件领域为单位的HiSysEvent打点屏蔽机制，方便开发者评估及调试HiSysEvent打点操作的影响。 ### 运作机制 -在进行HiSysEvent事件埋点之前，需要先完成HiSysEvent打点配置，具体配置方法请参考[HiSysEvent打点配置指导](subsys-dfx-hisysevent-logging-config.md)。 +在进行HiSysEvent事件打点之前，需要先完成HiSysEvent打点配置，具体配置方法请参考[HiSysEvent打点配置指导](subsys-dfx-hisysevent-logging-config.md)。 ## 开发指导 ### 场景介绍 -事件埋点的主要工作是将打点数据进行落盘。 +事件打点的主要工作是将打点数据进行落盘。 ### 接口说明 #### C++接口说明 -C++事件埋点开发能力如下：HiSysEvent类，具体的API详见接口文档 。 +C++事件打点开发能力如下：HiSysEvent类，具体API详见接口目录（/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent/include/）。 > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > -> 在OpenHarmony-3.2-Beta3版本中，为避免打点风暴事件引发性能问题，对HiSysEvent打点进行了管控。表1中的HiSysEvent::Write打点API接口被表2中的HiSysEventWrite宏接口取代。HiSysEvent::Write接口已废弃，请使用HiSysEventWrite宏完成HiSysEvent事件打点。 +> 从OpenHarmony-3.2-Beta3版本开始，为避免打点风暴事件引发性能问题，对HiSysEvent打点进行了管控。表1中的HiSysEvent::Write打点接口被表2中的HiSysEventWrite宏接口取代。HiSysEvent::Write接口已废弃，请使用HiSysEventWrite宏接口完成HiSysEvent事件打点。 -**表1** C++事件埋点API接口功能介绍（已废弃） +**表1** 事件打点接口（已废弃） | 接口名 | 描述 | | ------------------------------------------------------------ | --------------------- | -| template<typename... Types> 
static int Write(const std::string &domain, const std::string &eventName, EventType type, Types... keyValues) | 将打点事件数据进行落盘 | +| template<typename... Types> 
static int Write(const std::string &domain, const std::string &eventName, EventType type, Types... keyValues) | 将打点事件数据进行落盘。 | + +**表2** 事件打点宏接口 -**表2** C++事件埋点API接口功能介绍 | 接口名 | 描述 | | ------------------------------------------------------------ | --------------------- | -| HiSysEventWrite(domain, eventName, type, ...) | 将打点事件数据进行落盘 | +| HiSysEventWrite(domain, eventName, type, ...) | 将打点事件数据进行落盘。 | - **表3** C++事件类型介绍 + **表3** EventType事件类型枚举 | 事件类型 | 描述 | | --------- | ----------- | -| FAULT | 故障类型事件 | -| STATISTIC | 统计类型事件 | -| SECURITY | 安全类型事件 | -| BEHAVIOR | 行为类型事件 | +| FAULT | 故障类型事件。 | +| STATISTIC | 统计类型事件。 | +| SECURITY | 安全类型事件。 | +| BEHAVIOR | 行为类型事件。 | + +#### C接口说明 + +C事件打点开发能力如下：具体API详见接口目录（/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent/include/）。 + +**表4** 事件打点接口 + +| 接口名 | 描述 | +| ------------------------------------------------------------ | ------------------------ | +| int OH_HiSysEvent_Write(const char\* domain, const char\* name, HiSysEventEventType type, HiSysEventParam params[], size_t size); | 将打点事件数据进行落盘。 | + +**表5** HiSysEventEventType事件类型枚举 + +| 事件类型 | 描述 | +| -------------------- | -------------- | +| HISYSEVENT_FAULT | 故障类型事件。 | +| HISYSEVENT_STATISTIC | 统计类型事件。 | +| HISYSEVENT_SECURITY | 安全类型事件。 | +| HISYSEVENT_BEHAVIOR | 行为类型事件。 | + +**表6** HiSysEventParam事件参数结构体 + +| 属性名称 | 属性类型 | 描述 | +| --------- | -------------------- | ---------------------------------- | +| name | char name[] | 事件参数名称。 | +| t | HiSysEventParamType | 事件参数类型。 | +| v | HiSysEventParamValue | 事件参数值。 | +| arraySize | size_t | 事件参数值为数组类型时的数组长度。 | + +**表7** HiSysEventParamType事件参数类型枚举 + +| 参数类型 | 描述 | +| ----------------------- | -------------------------- | +| HISYSEVENT_INVALID | 无效类型事件参数。 | +| HISYSEVENT_BOOL | bool类型事件参数。 | +| HISYSEVENT_INT8 | int8_t类型事件参数。 | +| HISYSEVENT_UINT8 | uint8_t类型事件参数。 | +| HISYSEVENT_INT16 | int16_t类型事件参数。 | +| HISYSEVENT_UINT16 | uint16_t类型事件参数。 | +| HISYSEVENT_INT32 | int32_t类型事件参数。 | +| HISYSEVENT_UINT32 | uint32_t类型事件参数。 | +| HISYSEVENT_INT64 | int64_t类型事件参数。 | +| HISYSEVENT_UINT64 | uint64_t类型事件参数。 | +| HISYSEVENT_FLOAT | float类型事件参数。 | +| HISYSEVENT_DOUBLE | double类型事件参数。 | +| HISYSEVENT_STRING | char*类型事件参数。 | +| HISYSEVENT_BOOL_ARRAY | bool数组类型事件参数。 | +| HISYSEVENT_INT8_ARRAY | int8_t数组类型事件参数。 | +| HISYSEVENT_UINT8_ARRAY | uint8_t数组类型事件参数。 | +| HISYSEVENT_INT16_ARRAY | int16_t数组类型事件参数。 | +| HISYSEVENT_UINT16_ARRAY | uint16_t数组类型事件参数。 | +| HISYSEVENT_INT32_ARRAY | int32_t数组类型事件参数。 | +| HISYSEVENT_UINT32_ARRAY | uint32_t数组类型事件参数。 | +| HISYSEVENT_INT64_ARRAY | int64_t数组类型事件参数。 | +| HISYSEVENT_UINT64_ARRAY | uint64_t数组类型事件参数。 | +| HISYSEVENT_FLOAT_ARRAY | float数组类型事件参数。 | +| HISYSEVENT_DOUBLE_ARRAY | double数组类型事件参数。 | +| HISYSEVENT_STRING_ARRAY | char*数组类型事件参数。 | + +**表8** HiSysEventParamValue事件参数值联合体 + +| 属性名称 | 属性类型 | 描述 | +| -------- | -------- | ------------------------ | +| b | bool | bool类型事件参数值。 | +| i8 | int8_t | int8_t类型事件参数值。 | +| ui8 | uint8_t | uint8_t类型事件参数值。 | +| i16 | int16_t | int16_t类型事件参数值。 | +| ui16 | uint16_t | uint16_t类型事件参数值。 | +| i32 | int32_t | int32_t类型事件参数值。 | +| ui32 | uint32_t | uint32_t类型事件参数值。 | +| i64 | int64_t | int64_t类型事件参数值。 | +| ui64 | uint64_t | uint64_t类型事件参数值。 | +| f | float | float类型事件参数值。 | +| d | double | double类型事件参数值。 | +| s | char* | char*类型事件参数值。 | +| array | void* | 数组类型事件参数值。 | #### kernel接口说明 -kernel事件埋点开发能力如下： +kernel事件打点开发能力如下：具体API详见接口文件（/kernel/linux/linux-5.10/include/dfx/hiview_hisysevent.h）。 -**表4** kernel事件埋点API接口功能介绍 +**表9** 事件打点接口 | 接口名 | 描述 | | ------------------------------------------------------------ | ----------------------------------- | -| struct hiview_hisysevent *hisysevent_create(const char *domain, const char *name, enum hisysevent_type type); | 创建一个事件对象 | -| void hisysevent_destroy(struct hiview_hisysevent *event); | 销毁一个事件对象 | -| int hisysevent_put_integer(struct hiview_hisysevent *event, const char *key, long long value); | 将整数类型的事件参数添加到事件对象 | -| int hisysevent_put_string(struct hiview_hisysevent *event, const char *key, const char *value); | 将字符串类型的事件参数添加到事件对象 | -| int hisysevent_write(struct hiview_hisysevent *event); | 将事件对象数据进行落盘 | +| struct hiview_hisysevent *hisysevent_create(const char *domain, const char *name, enum hisysevent_type type); | 创建一个事件对象。 | +| void hisysevent_destroy(struct hiview_hisysevent *event); | 销毁一个事件对象。 | +| int hisysevent_put_integer(struct hiview_hisysevent *event, const char *key, long long value); | 将整数类型的事件参数添加到事件对象。 | +| int hisysevent_put_string(struct hiview_hisysevent *event, const char *key, const char *value); | 将字符串类型的事件参数添加到事件对象。 | +| int hisysevent_write(struct hiview_hisysevent *event); | 将事件对象数据进行落盘。 | -**表5** kernel事件类型介绍 +**表10** hisysevent_type事件类型枚举 | 事件类型 | 描述 | | --------- | ----------- | -| FAULT | 故障类型事件 | -| STATISTIC | 统计类型事件 | -| SECURITY | 安全类型事件 | -| BEHAVIOR | 行为类型事件 | +| FAULT | 故障类型事件。 | +| STATISTIC | 统计类型事件。 | +| SECURITY | 安全类型事件。 | +| BEHAVIOR | 行为类型事件。 | ### 开发步骤 -#### C++埋点开发步骤 +#### C++打点开发步骤 -1. 在需要埋点的地方直接调用埋点接口，并传入相应事件参数。 +在需要打点的地方直接调用打点接口，并传入相应事件参数。 ```c++ HiSysEventWrite(HiSysEvent::Domain::AAFWK, "START_APP", HiSysEvent::EventType::BEHAVIOR, "APP_NAME", "com.ohos.demo"); ``` -#### kernel埋点开发步骤 +#### C打点开发步骤 + +1. 如果需要在打点时传入自定义事件参数，先要根据事件参数类型创建对应的事件参数对象，再将其放入到事件参数数组中。 + + ```c + // 创建一个int32_t类型的事件参数 + HiSysEventParam param1 = { + .name = "KEY_INT32", + .t = HISYSEVENT_INT32, + .v = { .i32 = 1 }, + .arraySize = 0, + }; + + // 创建一个int32_t数组类型的事件参数 + 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]), + }; + + // 将事件参数对象放入创建的事件参数数组中 + HiSysEventParam params[] = { param1, param2 }; + ``` + +2. 在需要打点的地方调用打点接口，并传入相应事件参数。 + + ```c + OH_HiSysEvent_Write("TEST_DOMAIN", "TEST_NAME", HISYSEVENT_BEHAVIOR, params, sizeof(params) / sizeof(params[0])); + ``` + +#### kernel打点开发步骤 1. 根据事件领域、事件名称、事件类型参数，创建一个基础的事件对象。 @@ -141,9 +250,9 @@ kernel事件埋点开发能力如下： ### 开发实例 -#### C++埋点开发实例 +#### C++打点开发实例 -假设业务模块需要在应用启动时进行埋点来记录应用启动事件，且需要记录应用的包名信息，完整使用示例如下所示： +假设业务模块需要在应用启动时进行打点来记录应用启动事件，且需要记录应用的包名信息，完整使用示例如下所示： 1. 首先，需要在业务模块的在BUILD.gn里增加HiSysEvent部件依赖。 @@ -151,7 +260,7 @@ kernel事件埋点开发能力如下： external_deps = [ "hisysevent_native:libhisysevent" ] ``` -2. 在业务模块的应用启动函数StartAbility()中，调用埋点接口并传入对应事件参数。 +2. 在业务模块的应用启动函数StartAbility()中，调用打点接口并传入对应事件参数。 ```c++ #include "hisysevent.h" @@ -164,9 +273,40 @@ kernel事件埋点开发能力如下： } ``` -#### kernel埋点开发实例 +#### C打点开发实例 + +假设业务模块需要在应用启动时进行打点来记录应用启动事件，且需要记录应用的包名信息，完整使用示例如下所示： + +1. 首先，需要在业务模块的在BUILD.gn里增加HiSysEvent部件依赖。 + + ```c++ + external_deps = [ "hisysevent_native:libhisysevent" ] + ``` + +2. 在业务模块的应用启动函数StartAbility()中，调用打点接口并传入对应事件参数。 + + ```c + #include "hisysevent_c.h" + + int StartAbility() + { + ... // 其他业务逻辑 + 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])); + ... // 其他业务逻辑 + } + ``` + +#### kernel打点开发实例 -假设内核业务模块需要在设备启动时进行埋点来记录设备启动事件，完整使用示例如下所示： +假设内核业务模块需要在设备启动时进行打点来记录设备启动事件，完整使用示例如下所示： 1. 在设备启动函数device_boot()中，构建一个启动事件对象，然后将事件进行上报，最后销毁事件对象。 @@ -204,7 +344,6 @@ kernel事件埋点开发能力如下： - 假设业务模块中，需要在某个cpp文件中屏蔽名称分别为AAFWK和POWER的事件领域的打点，在该cpp文件引入hisysevent.h头文件之前，定义名称为DOMAIN_MASKS的宏： ```c++ - #define DOMAIN_MASKS "AAFWK|POWER" #include "hisysevent.h" @@ -212,14 +351,13 @@ kernel事件埋点开发能力如下： HiSysEventWrite(OHOS:HiviewDFX::HiSysEvent::Domain::AAFWK, "JS_ERROR", OHOS:HiviewDFX::HiSysEvent::EventType::FAULT, "MODULE", "com.ohos.module"); // 该HiSysEvent打点操作不会执行 ... // 其他业务逻辑 HiSysEventWrite(OHOS:HiviewDFX::HiSysEvent::Domain::POWER, "POWER_RUNNINGLOCK", OHOS:HiviewDFX::HiSysEvent::EventType::FAULT, "NAME", "com.ohos.module"); // 该HiSysEvent打点操作不会执行 - ``` - 假设需要在整个业务模块中屏蔽名称分别为AAFWK和POWER的事件领域的打点，在模块的BUILG.gn文件中定义名称为DOMAIN_MASKS的宏： ```gn config("module_a") { - ... // 其他配置项 - cflags_cc += ["-DDOMAIN_MASKS=\"AAFWK|POWER\""] + ... // 其他配置项 + cflags_cc += ["-DDOMAIN_MASKS=\"AAFWK|POWER\""] } ``` @@ -231,4 +369,4 @@ kernel事件埋点开发能力如下： # 参考 -HiSysEvent模块会将埋点数据写入到节点文件中，而埋点数据的解析处理会在Hiview模块中统一进行，详细处理过程可参考[Hiview开发指导](subsys-dfx-hiview.md)。 +HiSysEvent模块会将打点数据写入到节点文件中，而打点数据的解析处理会在Hiview模块中统一进行，详细处理过程可参考[Hiview开发指导](subsys-dfx-hiview.md)。 diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-query.md b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-query.md index 180706d7e4..9ea8b38594 100644 --- a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-query.md +++ b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-query.md @@ -8,105 +8,380 @@ HiSysEvent提供了查询接口，支持开发者设置条件查询HiSysEvent事 ## 开发指导 - ### 接口说明 +#### C++接口说明 + +C++ HiSysEvent查询开发能力如下：HiSysEventManager类，具体API详见接口目录（/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/）。 + > ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** > -> HiSysEventQueryCallback查询回调对象OnQuery方法中的形参类型HiSysEventRecord请参考[HiSysEvent订阅](subsys-dfx-hisysevent-listening.md)中的**表5**HiSysEventRecord系统事件对象说明 +> HiSysEventQueryCallback查询回调对象OnQuery方法中的形参类型HiSysEventRecord请参考[HiSysEvent订阅](subsys-dfx-hisysevent-listening.md)中的“表5 HiSysEventRecord系统事件对象”说明。 **表1** HiSysEvent查询接口 -| 接口名 | 描述 | +| 接口名称 | 描述 | | -------- | -------- | -| int32_t HiSysEventManager::Query(struct QueryArg& arg,
 std::vector<QueryRule>& rules,
 std::shared_ptr<HiSysEventQueryCallback> callback) | 接口功能：支持设置时间段，事件领域，事件名称等，查询满足条件的HiSysEvent事件。
输入参数：
- arg：查询参数。
- rules：事件过滤规则。
- callback：查询接口回调对象。
返回值：
- 0：查询成功。
- 负值：查询失败。 | +| int32_t Query(struct QueryArg& arg,
std::vector<QueryRule>& rules,
std::shared_ptr<HiSysEventQueryCallback> callback) | 接口功能：支持根据时间段、事件领域、事件名称等条件，查询满足条件的HiSysEvent事件。
输入参数：
- arg：查询参数。
- rules：事件过滤规则。
- callback：查询接口回调对象。
返回值：
- 0：查询成功。
- 负值：查询失败。 | **表2** QueryArg查询参数对象 -| 属性名称 | 描述 | -| -------- | -------- | -| beginTime | long long int类型，用于指定查询事件的开始时间。 | -| endTime | long long int类型，用于指定查询事件的结束时间。 | -| maxEvents | int类型，用于指定查询返回事件查询的最多条数。 | +| 属性名称 | 属性类型 | 描述 | +| -------- | -------- | -------- | +| beginTime | long long | 用于指定查询事件的开始时间，格式为Unix毫秒级时间戳。 | +| endTime | long long | 用于指定查询事件的结束时间，格式为Unix毫秒级时间戳。 | +| maxEvents | int | 用于指定查询返回事件的最多条数。 | **表3** QueryRule查询规则对象 | 接口名称 | 描述 | | -------- | -------- | -| QueryRule(const std::string& domain,
 const std::vector<std::string>& eventList) | 接口功能：查询规则构造函数，创建查询规则对象。
输入参数：
- domain：string类型，用来标识查询规则对象的事件所属领域，如果传入的是空字符串，则默认事件领域字段匹配成功。
- eventList：std::vector<std::string>类型，事件名称的列表，如果传入的是空字符串，则默认事件名称字段匹配成功。 | +| QueryRule(const std::string& domain,
const std::vector<std::string>& eventList) | 接口功能：查询规则构造函数，创建查询规则对象。
输入参数：
- domain：string类型，用来标识查询规则对象的事件所属领域，如果传入的是空字符串，则默认事件领域字段匹配成功。
- eventList：std::vector<std::string>类型，事件名称的列表，如果传入的是空字符串，则默认事件名称字段匹配成功。 | **表4** HiSysEventQueryCallback查询回调对象 | 接口名称 | 描述 | | -------- | -------- | -| void HiSysEventQueryCallback::OnQuery(std::shared_ptr<std::vector<HiSysEventRecord>> sysEvents) | 接口功能：事件查询的回调。
输入参数：
- sysEvents：返回的事件集合。
返回值：
无。 | -| void HiSysEventQueryCallback::OnComplete(int32_t reason, int32_t total) | 接口功能：事件查询完成的回调。
输入参数：
- reason：查询结束返回原因，目前默认是0。
- total：本次查询总共返回的事件总数量。
返回值：
无。 | +| void HiSysEventQueryCallback::OnQuery(std::shared_ptr<std::vector<HiSysEventRecord>> sysEvents) | 接口功能：事件查询的回调。
输入参数：
- sysEvents：返回的事件集合。 | +| void HiSysEventQueryCallback::OnComplete(int32_t reason, int32_t total) | 接口功能：事件查询完成的回调。
输入参数：
- reason：查询结束的返回原因，0表示查询正常结束，其他值表示查询异常结束。
- total：本次查询返回的事件的总数量。 | -### 开发实例 +#### C接口说明 -C++接口实例。 +C HiSysEvent查询开发能力如下：具体API详见接口目录（/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/）。 -1. 源代码开发： - 引入对应的头文件： + **表5** HiSysEvent查询接口 - ``` +| 接口名称 | 描述 | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| int OH_HiSysEvent_Query(const HiSysEventQueryArg& arg, HiSysEventQueryRule rules[], size_t ruleSize, HiSysEventQueryCallback& callback); | 接口功能：支持根据时间段、事件领域、事件名称、事件参数等条件，查询满足条件的HiSysEvent事件。
输入参数：
- arg：查询参数。
- rules：事件过滤规则。
- ruleSize：事件过滤规则数量。
- callback：查询接口回调。
返回值：
- 0：查询成功。
- 负值：查询失败。 | + + **表6** HiSysEventQueryArg查询参数结构体 + +| 属性名称 | 属性类型 | 描述 | +| --------- | -------- | ---------------------------------------------------- | +| beginTime | int64_t | 用于指定查询事件的开始时间，格式为Unix毫秒级时间戳。 | +| endTime | int64_t | 用于指定查询事件的结束时间，格式为Unix毫秒级时间戳。 | +| maxEvents | int32_t | 用于指定查询返回事件的最多条数。 | + +**表7** HiSysEventQueryRule查询规则结构体 + +| 属性名称 | 属性类型 | 描述 | +| ------------- | --------- | ---------------------------------- | +| domain | char[] | 用来指定查询的事件领域。 | +| eventList | char\[][] | 用于指定查询的事件名称列表。 | +| eventListSize | size_t | 用于指定查询的事件名称列表大小。 | +| condition | char* | 用于指定查询的自定义事件参数条件。 | + +对于condition参数需要按照指定的JSON字符串格式传入，使用实例如下： + +```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"} + ] + } +} +``` + +- version字段是必选字段，表示传入条件的支持版本，当前只支持V1版本。 +- condition字段是必选字段，表示传入条件的具体内容。 + - and字段是可选字段，表示条件之间是与的关系。 + - or字段是可选字段，表示条件之间是或的关系。 + - param字段是必选字段，表示条件匹配的参数名称，必须为字符串类型。 + - op字段是必选字段，表示条件匹配的参数比较符，必须为字符串类型，支持的比较符包括=、>、<、>=、<=。 + - value字段是必选字段，表示条件匹配的参数值，必须为字符串类型或整型。 + +**表8** HiSysEventQueryCallback查询回调结构体 + +| 属性名称 | 属性类型 | 描述 | +| ---------- | -------------------------------------------------- | ------------------------------------------------------------ | +| OnQuery | void (*)(HiSysEventRecord records[], size_t size); | 接口功能：事件查询的回调。
输入参数：
- records：返回的事件集合。
- size：返回的事件集合大小。 | +| OnComplete | void (*)(int32_t reason, int32_t total); | 接口功能：事件查询完成的回调。
输入参数：
- reason：查询结束的返回原因，0表示查询正常结束，其他值表示查询异常结束。
- total：本次查询返回的事件的总数量。 | + +**表9** HiSysEventRecord事件结构体 + +| 属性名称 | 属性类型 | 描述 | +| --------- | ------------------- | -------------------------- | +| domain | char[] | 事件的领域名称。 | +| eventName | char\[] | 事件的名称。 | +| type | HiSysEventEventType | 事件的类型。 | +| time | uint64_t | 事件的时间戳。 | +| tz | char\[] | 事件的时区。 | +| pid | int64_t | 事件的进程ID。 | +| tid | int64_t | 事件的线程ID。 | +| uid | int64_t | 事件的用户ID。 | +| traceId | uint64_t | 事件的分布式跟踪链ID。 | +| spandId | uint64_t | 事件的分布式跟踪分支ID。 | +| pspanId | uint64_t | 事件的分布式跟踪父分支ID。 | +| traceFlag | int | 事件的分布式跟踪标志位。 | +| level | char* | 事件的级别。 | +| tag | char* | 事件的标签。 | +| jsonStr | char* | 事件的内容。 | + +**表10** HiSysEventRecord解析接口 + +| 接口名称 | | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| void OH_HiSysEvent_GetParamNames(const HiSysEventRecord& record, char*** params, size_t& len); | 接口功能：获取该事件的所有的参数名。
输入参数：
- record：事件结构体。
- params：参数名数组。
- len：数组大小。 | +| int OH_HiSysEvent_GetParamInt64Value(const HiSysEventRecord& record, const char* name, int64_t& value); | 接口功能：将该事件中参数名为name的参数值，解析为int64_t类型并赋值到value。
输入参数：
- record：事件结构体。
- name：参数名。
- value：int64_t类型的参数值。 | +| int OH_HiSysEvent_GetParamUint64Value(const HiSysEventRecord& record, const char* name, uint64_t& value); | 接口功能：将该事件中参数名为name的参数值，解析为uint64_t类型并赋值到value。
输入参数：
- record：事件结构体。
- name：参数名。
- value：uint64_t类型的参数值。 | +| int OH_HiSysEvent_GetParamDoubleValue(const HiSysEventRecord& record, const char* name, double& value); | 接口功能：将该事件中参数名为name的参数值，解析为double类型并赋值到value。
输入参数：
- record：事件结构体。
- name：参数名。
- value：double类型的参数值。 | +| int OH_HiSysEvent_GetParamStringValue(const HiSysEventRecord& record, const char* name, char** value); | 接口功能：将该事件中参数名为name的参数值，解析为char数组类型并赋值到value，value在使用完成后需要手动释放内存。
输入参数：
- record：事件结构体。
- name：参数名。
- value：char\*类型引用。 | +| int OH_HiSysEvent_GetParamInt64Values(const HiSysEventRecord& record, const char* name, int64_t** value, size_t& len); | 接口功能：将该事件中参数名为name的参数值，解析为int64_t数组类型并赋值到value，value在使用完成后需要手动释放内存。
输入参数：
- record：事件结构体。
- name：参数名。
- value：int64_t\*类型引用。
- len：数组大小。 | +| int OH_HiSysEvent_GetParamUint64Values(const HiSysEventRecord& record, const char* name, uint64_t** value, size_t& len); | 接口功能：将该事件中参数名为name的参数值，解析为uint64_t数组类型并赋值到value，value在使用完成后需要手动释放内存。
输入参数：
- record：事件结构体。
- name：参数名。
- value：uint64_t\*类型引用。
- len：数组大小。 | +| int OH_HiSysEvent_GetParamDoubleValues(const HiSysEventRecord& record, const char* name, double** value, size_t& len); | 接口功能：将该事件中参数名为name的参数值，解析为double数组类型并赋值到value，value在使用完成后需要手动释放内存。
输入参数：
- record：事件结构体。
- name：参数名。
- value：double\*类型引用。
- len：数组大小。 | +| int OH_HiSysEvent_GetParamStringValues(const HiSysEventRecord& record, const char* name, char*** value, size_t& len); | 接口功能：将该事件中参数名为name的参数值，解析为char*数组类型并赋值到value，value在使用完成后需要手动释放内存。
输入参数：
- record：事件结构体。
- name：参数名。
- value：char\*\*类型引用。
- len：数组大小。 | + +HiSysEventRecord解析接口的返回值说明如下： + +- 0，表示解析成功； +- -1，表示该事件初始化失败； +- -2，表示参数名不存在； +- -3，表示要解析的参数值类型与传入的参数值类型不匹配。 + +### 开发步骤 + +#### C++ HiSysEvent查询开发步骤 + +1. 首先，需要引入对应的头文件。 + + ```c++ #include "hisysevent_manager.h" ``` - 实现对应的查询回调接口： +2. 然后，业务领域需要实现对应的查询回调接口。 - ``` - 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; + } + }; ``` - 在相应的业务逻辑里面调用查询接口： +3. 最后，在需要查询的地方调用查询接口，并传入相应的查询参数、查询规则、查询回调参数。 + ```c++ + // 创建查询参数对象 + long long startTime = 0; + long long endTime = 1668245644000; //2022-11-12 09:34:04 + int queryCount = 10; + QueryArg arg(startTime, endTime, queryCount); + + // 创建查询规则对象 + QueryRule rule("HIVIEWDFX", { "PLUGIN_LOAD" }); + std::vector queryRules = { rule }; + + // 创建查询回调对象 + auto queryCallback = std::make_shared(); + + // 调用查询接口 + HiSysEventManager::Query(arg, queryRules, queryCallback); ``` - HiSysEventManager::Query(struct QueryArg& queryArg, - std::vector& queryRules, std::shared_ptr queryCallBack) - ``` - 以下是查询所有系统事件的应用例子： +#### C HiSysEvent查询开发步骤 + +1. 首先，需要引入对应的头文件。 + ```c++ + #include "hisysevent_manager_c.h" ``` - #include "hisysevent_manager.h" - #include - namespace OHOS { - namespace HiviewDFX { - // 实现查询回调的接口 - void HiSysEventToolQuery::OnQuery(std::shared_ptr> sysEvents) +2. 然后，业务领域需要实现对应的查询回调接口。 + + ```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 - - // 调用查询接口获取HiSysEvent事件 - auto queryCallBack = std::make_shared(); - struct QueryArg args(clientCmdArg.beginTime, clientCmdArg.endTime, clientCmdArg.maxEvents); - std::vector rules; - HiSysEventManager::QueryHiSysEvent(args, rules, queryCallBack); ``` -2. 编译设置： - 在BUILD.gn编译文件中，需要添加依赖hisysevent_native部件的libhisysevent及libhisyseventmanager库。 - +3. 最后，在需要查询的地方调用查询接口，并传入相应的查询参数、查询规则、查询回调参数。 + + ```c++ + // 创建查询参数对象 + HiSysEventQueryArg arg; + arg.beginTime = 0; + arg.endTime = 1668245644000; //2022-11-12 09:34:04 + arg.maxEvents = 10; + + // 创建查询规则对象 + 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 }; + + // 创建查询回调对象 + HiSysEventQueryCallback callback; + callback.OnQuery = OnQueryTest; + callback.OnComplete = OnCompleteTest; + + // 调用查询接口 + OH_HiSysEvent_Query(arg, rules, sizeof(rules) / sizeof(HiSysEventQueryRule), callback); ``` + +### 开发实例 + +#### C++ HiSysEvent查询开发实例 + +假设业务模块需要查询截止至当前时间、事件领域为HIVIEWDFX、事件名称为PLUGIN_LOAD的所有事件，其完整使用示例如下所示： + +1. 首先，需要在业务模块的在BUILD.gn里增加hisysevent_native部件的libhisysevent及libhisyseventmanager依赖。 + + ```c++ external_deps = [ "hisysevent_native:libhisysevent", "hisysevent_native:libhisyseventmanager", ] ``` +2. 在业务模块的TestQuery()函数中，调用查询接口去查询事件。 + + ```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() + { + // 创建查询参数对象 + long long startTime = 0; + long long endTime = GetMilliseconds(); + int maxEvents = 100; + QueryArg arg(startTime, endTime, maxEvents); + + // 创建查询规则对象 + QueryRule rule("HIVIEWDFX", { "PLUGIN_LOAD" }); + std::vector queryRules = { rule }; + + // 创建查询回调对象 + auto queryCallback = std::make_shared(); + + // 调用查询接口 + int ret = HiSysEventManager::Query(arg, queryRules, queryCallback); + } + ``` + +#### C HiSysEvent查询开发实例 + +假设业务模块需要查询截止至当前时间、事件领域为HIVIEWDFX、事件名称为PLUGIN_LOAD的所有事件，其完整使用示例如下所示： + +1. 首先，需要在业务模块的在BUILD.gn里增加hisysevent_native部件的libhisyseventmanager依赖。 + + ```c++ + external_deps = [ "hisysevent_native:libhisyseventmanager" ] + + // for strcpy_s + deps = [ "//third_party/bounds_checking_function:libsec_shared" ] + ``` + +2. 在业务模块的TestQuery()函数中，调用查询接口去查询事件。 + + ```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() + { + // 创建查询参数对象 + HiSysEventQueryArg arg; + arg.beginTime = 0; + arg.endTime = GetMilliseconds(); + arg.maxEvents = 100; + + // 创建查询规则对象 + 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 }; + + // 创建查询回调对象 + HiSysEventQueryCallback callback; + callback.OnQuery = OnQueryTest; + callback.OnComplete = OnCompleteTest; + + // 调用查询接口 + int ret = OH_HiSysEvent_Query(arg, rules, sizeof(rules) / sizeof(HiSysEventQueryRule), callback); + } + ``` -- GitLab