1# HiSysEvent查询 2 3 4## 概述 5 6HiSysEvent提供了查询接口，支持开发者设置条件查询HiSysEvent事件，例如功耗部件可以通过该接口获取所需的系统事件进行业务分析。 7 8 9## 开发指导 10 11### 接口说明 12 13#### C++接口说明 14 15C++ HiSysEvent查询开发能力如下：HiSysEventManager类，具体API详见接口目录（/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/）。 16 17>  **说明：** 18> 19> HiSysEventQueryCallback查询回调对象OnQuery方法中的形参类型HiSysEventRecord请参考[HiSysEvent订阅](subsys-dfx-hisysevent-listening.md)中的“表4 HiSysEventRecord系统事件对象”说明。 20 21 **表1** HiSysEvent查询接口 22 23| 接口名称 | 描述 | 24| -------- | -------- | 25| int32_t Query(struct QueryArg& arg,<br/>std::vector<QueryRule>& rules,<br/>std::shared_ptr<HiSysEventQueryCallback> callback) | 接口功能：支持根据时间段、事件领域、事件名称等条件，查询满足条件的HiSysEvent事件。<br/>输入参数：<br/>- arg：查询参数。<br/>- rules：事件过滤规则。<br/>- callback：查询接口回调对象。<br/>返回值：<br/>- 0：查询成功。<br/>- 负值：查询失败。 | 26 27 **表2** QueryArg查询参数对象 28 29| 属性名称 | 属性类型 | 描述 | 30| -------- | -------- | -------- | 31| beginTime | long long | 用于指定查询事件的开始时间，格式为Unix毫秒级时间戳。 | 32| endTime | long long | 用于指定查询事件的结束时间，格式为Unix毫秒级时间戳。 | 33| maxEvents | int | 用于指定查询返回事件的最多条数。 | 34 35 **表3** EventType事件类型枚举 36 37| 事件类型 | 值 | 描述 | 38| ------------ | ---- | ------------------ | 39| FAULT | 1 | 故障类型。 | 40| STATISTIC | 2 | 统计类型。 | 41| SECURITY | 3 | 安全类型。 | 42| BEHAVIOR | 4 | 用户行为类型。 | 43 44 **表4** RuleType匹配规则类型枚举 45 46| 查询规则类型 | 值 | 描述 | 47| ------------ | ---- | ------------------ | 48| WHOLE_WORD | 1 | 全词匹配类型。 | 49| PREFIX | 2 | 前缀匹配类型。 | 50| REGULAR | 3 | 正则匹配类型。 | 51 52 **表5** QueryRule查询规则对象 53 54| 接口名称 | 描述 | 55| -------- | -------- | 56| QueryRule(const std::string& domain,<br/>const std::vector<std::string>& eventList,<br/>RuleType ruleType,<br/>uint32_t eventType,<br/>const std::string& cond) | 接口功能：查询规则构造函数，创建查询规则对象。<br/>输入参数：<br/>- domain：string类型，用来标识查询规则对象的事件所属领域，如果传入的是空字符串，则默认事件领域字段匹配成功。<br/>- eventList：std::vector<std::string>类型，事件名称的列表，如果传入的是空字符串，则默认事件名称字段匹配成功。<br/>- ruleType：RuleType类型，请参考表4。<br/>- eventType：uint32_t类型，查询的系统事件类型，系统事件类型请参考表3，当eventType取值为0时，表示查询所有事件类型。<br/>- cond：string类型，设置的系统事件查询条件。 | 57 58对于condition参数需要按照指定的JSON字符串格式传入，使用实例如下： 59 60 ```json 61 { 62 "version":"V1", 63 "condition":{ 64 "and":[ 65 {"param":"type_","op":">","value":0}, 66 {"param":"uid_","op":"=","value":1201} 67 ] 68 } 69 } 70 ``` 71- version字段是必选字段，表示传入条件的支持版本，当前只支持V1版本。 72- condition字段是必选字段，表示传入条件的具体内容。 73 - and字段是可选字段，表示条件之间是与的关系。 74 - param字段是必选字段，表示条件匹配的参数名称，必须为字符串类型。 75 - op字段是必选字段，表示条件匹配的参数比较符，必须为字符串类型，支持的比较符包括=、>、<、>=、<=。 76 - value字段是必选字段，表示条件匹配的参数值，必须为字符串类型或整型。 77 78 79 80 81 82**表6** HiSysEventQueryCallback查询回调对象 83 84| 接口名称 | 描述 | 85| -------- | -------- | 86| void HiSysEventQueryCallback::OnQuery(std::shared_ptr<std::vector<HiSysEventRecord>> sysEvents) | 接口功能：事件查询的回调。<br/>输入参数：<br/>- sysEvents：返回的事件集合。 | 87| void HiSysEventQueryCallback::OnComplete(int32_t reason, int32_t total) | 接口功能：事件查询完成的回调。<br/>输入参数：<br/>- reason：查询结束的返回原因，0表示查询正常结束，其他值表示查询异常结束。<br/>- total：本次查询返回的事件的总数量。 | 88 89#### C接口说明 90 91C HiSysEvent查询开发能力如下：具体API详见接口目录（/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent_manager/include/）。 92 93 **表7** HiSysEvent查询接口 94 95| 接口名称 | 描述 | 96| ------------------------------------------------------------ | ------------------------------------------------------------ | 97| int OH_HiSysEvent_Query(const HiSysEventQueryArg& arg, HiSysEventQueryRule rules[], size_t ruleSize, HiSysEventQueryCallback& callback); | 接口功能：支持根据时间段、事件领域、事件名称、事件参数等条件，查询满足条件的HiSysEvent事件。<br/>输入参数：<br/>- arg：查询参数。<br/>- rules：事件过滤规则。<br/>- ruleSize：事件过滤规则数量。<br/>- callback：查询接口回调。<br/>返回值：<br/>- 0：查询成功。<br/>- 负值：查询失败。 | 98 99 **表8** HiSysEventQueryArg查询参数结构体 100 101| 属性名称 | 属性类型 | 描述 | 102| --------- | -------- | ---------------------------------------------------- | 103| beginTime | int64_t | 用于指定查询事件的开始时间，格式为Unix毫秒级时间戳。 | 104| endTime | int64_t | 用于指定查询事件的结束时间，格式为Unix毫秒级时间戳。 | 105| maxEvents | int32_t | 用于指定查询返回事件的最多条数。 | 106 107 **表9** HiSysEventQueryRule查询规则结构体 108 109| 属性名称 | 属性类型 | 描述 | 110| ------------- | --------- | ---------------------------------- | 111| domain | char[] | 用来指定查询的事件领域。 | 112| eventList | char\[][] | 用于指定查询的事件名称列表。 | 113| eventListSize | size_t | 用于指定查询的事件名称列表大小。 | 114| condition | char* | 用于指定查询的自定义事件参数条件。 | 115 116 **表10** HiSysEventQueryCallback查询回调结构体 117 118| 属性名称 | 属性类型 | 描述 | 119| ---------- | -------------------------------------------------- | ------------------------------------------------------------ | 120| OnQuery | void (*)(HiSysEventRecord records[], size_t size); | 接口功能：事件查询的回调。<br/>输入参数：<br/>- records：返回的事件集合。<br/>- size：返回的事件集合大小。 | 121| OnComplete | void (*)(int32_t reason, int32_t total); | 接口功能：事件查询完成的回调。<br/>输入参数：<br/>- reason：查询结束的返回原因，0表示查询正常结束，其他值表示查询异常结束。<br/>- total：本次查询返回的事件的总数量。 | 122 123 **表11** HiSysEventRecord事件结构体 124 125| 属性名称 | 属性类型 | 描述 | 126| --------- | ------------------- | -------------------------- | 127| domain | char[] | 事件的领域名称。 | 128| eventName | char\[] | 事件的名称。 | 129| type | HiSysEventEventType | 事件的类型。 | 130| time | uint64_t | 事件的时间戳。 | 131| tz | char\[] | 事件的时区。 | 132| pid | int64_t | 事件的进程ID。 | 133| tid | int64_t | 事件的线程ID。 | 134| uid | int64_t | 事件的用户ID。 | 135| traceId | uint64_t | 事件的分布式跟踪链ID。 | 136| spandId | uint64_t | 事件的分布式跟踪分支ID。 | 137| pspanId | uint64_t | 事件的分布式跟踪父分支ID。 | 138| traceFlag | int | 事件的分布式跟踪标志位。 | 139| level | char* | 事件的级别。 | 140| tag | char* | 事件的标签。 | 141| jsonStr | char* | 事件的内容。 | 142 143 **表12** HiSysEventRecord解析接口 144 145| 接口名称 | | 146| ------------------------------------------------------------ | ------------------------------------------------------------ | 147| void OH_HiSysEvent_GetParamNames(const HiSysEventRecord& record, char*** params, size_t& len); | 接口功能：获取该事件的所有的参数名。<br/>输入参数：<br/>- record：事件结构体。<br/>- params：参数名数组。<br/>- len：数组大小。 | 148| int OH_HiSysEvent_GetParamInt64Value(const HiSysEventRecord& record, const char* name, int64_t& value); | 接口功能：将该事件中参数名为name的参数值，解析为int64_t类型并赋值到value。<br/>输入参数：<br/>- record：事件结构体。<br/>- name：参数名。<br/>- value：int64_t类型的参数值。 | 149| int OH_HiSysEvent_GetParamUint64Value(const HiSysEventRecord& record, const char* name, uint64_t& value); | 接口功能：将该事件中参数名为name的参数值，解析为uint64_t类型并赋值到value。<br/>输入参数：<br/>- record：事件结构体。<br/>- name：参数名。<br/>- value：uint64_t类型的参数值。 | 150| int OH_HiSysEvent_GetParamDoubleValue(const HiSysEventRecord& record, const char* name, double& value); | 接口功能：将该事件中参数名为name的参数值，解析为double类型并赋值到value。<br/>输入参数：<br/>- record：事件结构体。<br/>- name：参数名。<br/>- value：double类型的参数值。 | 151| int OH_HiSysEvent_GetParamStringValue(const HiSysEventRecord& record, const char* name, char** value); | 接口功能：将该事件中参数名为name的参数值，解析为char数组类型并赋值到value，value在使用完成后需要手动释放内存。<br/>输入参数：<br/>- record：事件结构体。<br/>- name：参数名。<br/>- value：char\*类型引用。 | 152| int OH_HiSysEvent_GetParamInt64Values(const HiSysEventRecord& record, const char* name, int64_t** value, size_t& len); | 接口功能：将该事件中参数名为name的参数值，解析为int64_t数组类型并赋值到value，value在使用完成后需要手动释放内存。<br/>输入参数：<br/>- record：事件结构体。<br/>- name：参数名。<br/>- value：int64_t\*类型引用。<br/>- len：数组大小。 | 153| int OH_HiSysEvent_GetParamUint64Values(const HiSysEventRecord& record, const char* name, uint64_t** value, size_t& len); | 接口功能：将该事件中参数名为name的参数值，解析为uint64_t数组类型并赋值到value，value在使用完成后需要手动释放内存。<br/>输入参数：<br/>- record：事件结构体。<br/>- name：参数名。<br/>- value：uint64_t\*类型引用。<br/>- len：数组大小。 | 154| int OH_HiSysEvent_GetParamDoubleValues(const HiSysEventRecord& record, const char* name, double** value, size_t& len); | 接口功能：将该事件中参数名为name的参数值，解析为double数组类型并赋值到value，value在使用完成后需要手动释放内存。<br/>输入参数：<br/>- record：事件结构体。<br/>- name：参数名。<br/>- value：double\*类型引用。<br/>- len：数组大小。 | 155| int OH_HiSysEvent_GetParamStringValues(const HiSysEventRecord& record, const char* name, char*** value, size_t& len); | 接口功能：将该事件中参数名为name的参数值，解析为char*数组类型并赋值到value，value在使用完成后需要手动释放内存。<br/>输入参数：<br/>- record：事件结构体。<br/>- name：参数名。<br/>- value：char\*\*类型引用。<br/>- len：数组大小。 | 156 157HiSysEventRecord解析接口的返回值说明如下： 158 159- 0，表示解析成功； 160- -1，表示该事件初始化失败； 161- -2，表示参数名不存在； 162- -3，表示要解析的参数值类型与传入的参数值类型不匹配。 163 164### 开发步骤 165 166#### C++ HiSysEvent查询开发步骤 167 1681. 引入对应的头文件。 169 170 ```c++ 171 #include "hisysevent_manager.h" 172 ``` 173 1742. 业务领域实现对应的查询回调接口。 175 176 ```c++ 177 class TestQueryCallback : public HiSysEventQueryCallback { 178 public: 179 void OnQuery(std::shared_ptr<std::vector<HiSysEventRecord>> sysEvents) override 180 { 181 if (sysEvents == nullptr) { 182 return; 183 } 184 for_each((*sysEvents).cbegin(), (*sysEvents).cend(), [](const HiSysEventRecord& event) { 185 std::cout << event.AsJson() << std::endl; 186 }); 187 } 188 189 void OnComplete(int32_t reason, int32_t total) override 190 { 191 std::cout << "Query completed" << std::endl; 192 return; 193 } 194 }; 195 ``` 196 1973. 在查询的地方调用查询接口，并传入相应的查询参数、查询规则、查询回调参数。 198 199 ```c++ 200 // 创建查询参数对象 201 long long startTime = 0; 202 long long endTime = 1668245644000; //2022-11-12 09:34:04 203 int queryCount = 10; 204 QueryArg arg(startTime, endTime, queryCount); 205 206 // 创建查询规则对象 207 QueryRule rule("HIVIEWDFX", { "PLUGIN_LOAD" }); 208 std::vector<QueryRule> queryRules = { rule }; 209 210 // 创建查询回调对象 211 auto queryCallback = std::make_shared<TestQueryCallback>(); 212 213 // 调用查询接口 214 HiSysEventManager::Query(arg, queryRules, queryCallback); 215 ``` 216 217#### C HiSysEvent查询开发步骤 218 2191. 引入对应的头文件。 220 221 ```c++ 222 #include "hisysevent_manager_c.h" 223 ``` 224 2252. 业务领域实现对应的查询回调接口。 226 227 ```c++ 228 void OnQueryTest(HiSysEventRecord records[], size_t size) 229 { 230 for (size_t i = 0; i < size; i++) { 231 printf("OnQuery: event=%s", records[i].jsonStr); 232 } 233 } 234 235 void OnCompleteTest(int32_t reason, int32_t total) 236 { 237 printf("OnCompleted, res=%d, total=%d\n", reason, total); 238 } 239 ``` 240 2413. 在查询的地方调用查询接口，并传入相应的查询参数、查询规则、查询回调参数。 242 243 ```c++ 244 // 创建查询参数对象 245 HiSysEventQueryArg arg; 246 arg.beginTime = 0; 247 arg.endTime = 1668245644000; //2022-11-12 09:34:04 248 arg.maxEvents = 10; 249 250 // 创建查询规则对象 251 constexpr char TEST_DOMAIN[] = "HIVIEWDFX"; 252 constexpr char TEST_NAME[] = "PLUGIN_LOAD"; 253 HiSysEventQueryRule rule; 254 (void)strcpy_s(rule.domain, strlen(TEST_DOMAIN) + 1, TEST_DOMAIN); 255 (void)strcpy_s(rule.eventList[0], strlen(TEST_NAME) + 1, TEST_NAME); 256 rule.eventListSize = 1; 257 rule.condition = nullptr; 258 HiSysEventQueryRule rules[] = { rule }; 259 260 // 创建查询回调对象 261 HiSysEventQueryCallback callback; 262 callback.OnQuery = OnQueryTest; 263 callback.OnComplete = OnCompleteTest; 264 265 // 调用查询接口 266 OH_HiSysEvent_Query(arg, rules, sizeof(rules) / sizeof(HiSysEventQueryRule), callback); 267 ``` 268 269### 开发实例 270 271#### C++ HiSysEvent查询开发实例 272 273假设业务模块需要查询截止至当前时间、事件领域为HIVIEWDFX、事件名称为PLUGIN_LOAD的所有事件，其完整使用示例如下所示： 274 2751. 在业务模块的在BUILD.gn里增加hisysevent部件的libhisysevent及libhisyseventmanager依赖。 276 277 ```c++ 278 external_deps = [ 279 "hisysevent:libhisysevent", 280 "hisysevent:libhisyseventmanager", 281 ] 282 ``` 283 2842. 在业务模块的TestQuery()函数中，调用查询接口去查询事件。 285 286 ```c++ 287 #include "hisysevent_manager.h" 288 #include <iostream> 289 #include <unistd.h> 290 291 using namespace OHOS::HiviewDFX; 292 293 class TestQueryCallback : public HiSysEventQueryCallback { 294 public: 295 void OnQuery(std::shared_ptr<std::vector<HiSysEventRecord>> sysEvents) override 296 { 297 if (sysEvents == nullptr) { 298 return; 299 } 300 for_each((*sysEvents).cbegin(), (*sysEvents).cend(), [](const HiSysEventRecord& event) { 301 std::cout << event.AsJson() << std::endl; 302 }); 303 } 304 305 void OnComplete(int32_t reason, int32_t total) override 306 { 307 std::cout << "Query completed" << std::endl; 308 return; 309 } 310 }; 311 312 int64_t GetMilliseconds() 313 { 314 auto now = std::chrono::system_clock::now(); 315 auto millisecs = std::chrono::duration_cast<std::chrono::milliseconds>(now.time_since_epoch()); 316 return millisecs.count(); 317 } 318 319 void TestQuery() 320 { 321 long long startTime = 0; 322 long long endTime = GetMilliseconds(); 323 int maxEvents = 100; 324 QueryArg arg(startTime, endTime, maxEvents); 325 QueryRule rule("HIVIEWDFX", { "PLUGIN_LOAD" }); 326 std::vector<QueryRule> queryRules = { rule }; 327 auto queryCallback = std::make_shared<TestQueryCallback>(); 328 int ret = HiSysEventManager::Query(arg, queryRules, queryCallback); 329 } 330 ``` 331 332#### C HiSysEvent查询开发实例 333 334假设业务模块需要查询截止至当前时间、事件领域为HIVIEWDFX、事件名称为PLUGIN_LOAD的所有事件，其完整使用示例如下所示： 335 3361. 在业务模块的在BUILD.gn里增加hisysevent部件的libhisyseventmanager依赖。 337 338```c++ 339 external_deps = [ "hisysevent:libhisyseventmanager" ] 340 341 // for strcpy_s 342 deps = [ "//third_party/bounds_checking_function:libsec_shared" ] 343``` 344 3452. 在业务模块的TestQuery()函数中，调用查询接口去查询事件。 346 347 ```c++ 348 #include "hisysevent_manager_c.h" 349 #include <securec.h> 350 #include <time.h> 351 352 void OnQueryTest(HiSysEventRecord records[], size_t size) 353 { 354 for (size_t i = 0; i < size; i++) { 355 printf("OnQuery: event=%s", records[i].jsonStr); 356 } 357 } 358 359 void OnCompleteTest(int32_t reason, int32_t total) 360 { 361 printf("OnCompleted, res=%d, total=%d\n", reason, total); 362 } 363 364 int64_t GetMilliseconds() 365 { 366 return time(NULL); 367 } 368 369 void TestQuery() 370 { 371 HiSysEventQueryArg arg; 372 arg.beginTime = 0; 373 arg.endTime = GetMilliseconds(); 374 arg.maxEvents = 100; 375 constexpr char TEST_DOMAIN[] = "HIVIEWDFX"; 376 constexpr char TEST_NAME[] = "PLUGIN_LOAD"; 377 HiSysEventQueryRule rule; 378 (void)strcpy_s(rule.domain, strlen(TEST_DOMAIN) + 1, TEST_DOMAIN); 379 (void)strcpy_s(rule.eventList[0], strlen(TEST_NAME) + 1, TEST_NAME); 380 rule.eventListSize = 1; 381 rule.condition = nullptr; 382 HiSysEventQueryRule rules[] = { rule }; 383 HiSysEventQueryCallback callback; 384 callback.OnQuery = OnQueryTest; 385 callback.OnComplete = OnCompleteTest; 386 int ret = OH_HiSysEvent_Query(arg, rules, sizeof(rules) / sizeof(HiSysEventQueryRule), callback); 387 } 388 ``` 389
