openharmony 鸿蒙 subsys-dfx-hisysevent-query

2022-08-09 浏览 (768)

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

NameDescription
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: event filtering rules.
- callback: callback object for event query.
Return value:
- 0: Query is successful.
- A negative value: Query has failed.

Table 2 Description of QueryArg objects

FieldTypeDescription
beginTimelong longStart time for query. The value is a Unix timestamp, in milliseconds.
endTimelong longEnd time for query. The value is a Unix timestamp, in milliseconds.
maxEventsintMaximum number of returned events.

Table 3 Description of EventType enums

Event TypeValueDescription
FAULT1Fault type.
STATISTIC2Statistical type.
SECURITY3Security type.
BEHAVIOR4User behavior type.

Table 4 RuleType enum values

Rule TypeValueDescription
WHOLE_WORD1Whole word matching.
PREFIX2Prefix matching.
REGULAR3Regular expression matching.

Table 5 Description of QueryRule objects

NameDescription
QueryRule(const std::string& domain,
const std::vector<std::string>& eventList,
RuleType ruleType,
uint32_t eventType,
const std::string& cond)		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.
- ruleType: rule type. For details, see Table 4.
- eventType: system event type. The value is of the uint32_t type. For details about the system event types, see Table 3. When eventType is set to 0, all types of events are queried.
- cond: query criteria. The value is of the string type.

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

NameDescription
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 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

NameDescription
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: event filtering rules.
- 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 8 Description of the HiSysEventQueryArg structure

FieldTypeDescription
beginTimeint64_tStart time for query. The value is a Unix timestamp, in milliseconds.
endTimeint64_tEnd time for query. The value is a Unix timestamp, in milliseconds.
maxEventsint32_tMaximum number of returned events.

Table 9 Description of the HiSysEventQueryRule structure

FieldTypeDescription
domainchar[]Event domain.
eventListchar[][]Event name list.
eventListSizesize_tSize of the event name list.
conditionchar*Custom event parameter conditions for the query.

Table 10 Description of the HiSysEventQueryCallback structure

FieldTypeDescription
OnQueryvoid (*)(HiSysEventRecord records[], size_t size);Callback object for event query.
Input arguments:
- records: event list.
- size: size of the event list.
OnCompletevoid (*)(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 11 Description of the HiSysEventRecord event structure

FieldTypeDescription
domainchar[]Event domain.
eventNamechar[]Event name.
typeHiSysEventEventTypeEvent type.
timeuint64_tEvent timestamp.
tzchar[]Event time zone.
pidint64_tProcess ID of the event.
tidint64_tThread ID of the event.
uidint64_tUser ID of the event.
traceIduint64_tDistributed call chain trace ID of the event.
spandIduint64_tSpan ID for the distributed call chain trace of the event.
pspanIduint64_tParent span ID for the distributed call chain trace of the event.
traceFlagintDistributed call chain trace flag of the event.
levelchar*Event level.
tagchar*Event tag.
jsonStrchar*Event content.

Table 12 Description of HiSysEventRecord APIs

Name
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 a 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++ 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" ]

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Subsystems

harmony 鸿蒙AI Framework Development Guide

harmony 鸿蒙Neural Network Runtime Device Access

harmony 鸿蒙Application Privilege Configuration

harmony 鸿蒙Development Example

harmony 鸿蒙Setting Up a Development Environment

harmony 鸿蒙Development Guidelines

harmony 鸿蒙Application Framework Overview

harmony 鸿蒙ArkCompiler Development

harmony 鸿蒙Window Title Bar Customization Development (ArkTS)

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/6819375e7f6542b5b26fe72e3bbda8ec