HiSysEvent Query

Overview

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.

How to Develop

Available APIs

C++ APIs

HiSysEvent query is implemented using the API provided by the HiSysEventManager class. For details, see the API Header Files.

NOTE

For details about HiSysEventRecord in the OnQuery() API of HiSysEventQueryCallback, see Table 4 in HiSysEvent Listening.

Table 1 Description of the C++ HiSysEvent query API

Table 2 Description of QueryArg objects

Table 3 Description of EventType enums

Table 4 RuleType enum values

Table 5 Description of QueryRule objects

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}
        ]
    }
}
```

• 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 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 6 Description of HiSysEventQueryCallback objects

C APIs

HiSysEvent query is implemented using the API provided in the following table. For details, see the API Header Files.

Table 7 Description of the C HiSysEvent query API

Table 8 Description of the HiSysEventQueryArg structure

Table 9 Description of the HiSysEventQueryRule structure

Table 10 Description of the HiSysEventQueryCallback structure

Table 11 Description of the HiSysEventRecord event structure

Table 12 Description of HiSysEventRecord APIs

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++ HiSysEvent Query

1. Import the corresponding header file.

   #include "hisysevent_manager.h"
   

2. Implement the callback API for the service domain.

   class TestQueryCallback : public HiSysEventQueryCallback {
   public:
       void OnQuery(std::shared_ptr<std::vector<HiSysEventRecord>> 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. Call the query API while passing in QueryArg, QueryRule, and QueryCallback.

   // Create a QueryArg 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 QueryRule object.
   QueryRule rule("HIVIEWDFX", { "PLUGIN_LOAD" });
   std::vector<QueryRule> queryRules = { rule };
   
   // Create a QueryCallback object.
   auto queryCallback = std::make_shared<TestQueryCallback>();
   
   // Call the query API.
   HiSysEventManager::Query(arg, queryRules, queryCallback);
   

C HiSysEvent Query

1. Import the corresponding header file.

   #include "hisysevent_manager_c.h"
   

2. Implement the callback API for the service domain.

   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);
   }
   

3. Call the query API while passing in HiSysEventQueryArg, HiSysEventQueryRule, and HiSysEventQueryCallback.

   // Create a HiSysEventQueryArg object.
   HiSysEventQueryArg arg;
   arg.beginTime = 0;
   arg.endTime = 1668245644000; //2022-11-12 09:34:04
   arg.maxEvents = 10;
   
   // Create a HiSysEventQueryRule 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 HiSysEventQueryCallback object.
   HiSysEventQueryCallback callback;
   callback.OnQuery = OnQueryTest;
   callback.OnComplete = OnCompleteTest;
   
   // Call the query API.
   OH_HiSysEvent_Query(arg, rules, sizeof(rules) / sizeof(HiSysEventQueryRule), callback);
   

Development Examples

C++ HiSysEvent Query

Suppose you want to query all events generated up to the current time with domain being HIVIEWDFX and name being PLUGIN_LOAD. The sample code is as follows:

1. Add the libhisysevent and libhisyseventmanager dependencies of the hisysevent component to the BUILD.gn file of the service module.

   external_deps = [
     "hisysevent:libhisysevent",
     "hisysevent:libhisyseventmanager",
   ]
   

2. Call the query API in the TestQuery() function of the service module.

   #include "hisysevent_manager.h"
   #include <iostream>
   #include <unistd.h>
   
   using namespace OHOS::HiviewDFX;
   
   class TestQueryCallback : public HiSysEventQueryCallback {
   public:
       void OnQuery(std::shared_ptr<std::vector<HiSysEventRecord>> 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<std::chrono::milliseconds>(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<QueryRule> queryRules = { rule };
       auto queryCallback = std::make_shared<TestQueryCallback>();
       int ret = HiSysEventManager::Query(arg, queryRules, queryCallback);
   }
   

C HiSysEvent Query

Suppose you want to query all events generated up to the current time with domain being HIVIEWDFX and name being PLUGIN_LOAD. The sample code is as follows:

1. Add the libhisyseventmanager dependency of the hisysevent component to the BUILD.gn file of the service module.

    external_deps = [ "hisysevent: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.

   #include "hisysevent_manager_c.h"
   #include <securec.h>
   #include <time.h>
    
   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);
   }