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