Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
“b342561535bcd177da662ea9964eba7efe05f589”上不存在“tests/system-test/git@gitcode.net:taosdata/tdengine.git”
提交 159b7ccf 编写于 作者: S shawn_he
浏览文件
操作

update doc 

Signed-off-by: Nshawn_he <shawn.he@huawei.com>
上级 2343fe81
展开全部 隐藏空白更改
内联 并排
Showing with 512 addition and 98 deletion
en/device-dev/subsystems/subsys-dfx-hisysevent-logging.md
浏览文件 @ 159b7ccf
...@@ -2,83 +2,192 @@ ...@@ -2,83 +2,192 @@
## Overview ## Overview
### Function ### Function Introduction
HiSysEvent provides event logging APIs for OpenHarmony to record important information of key processes during system running. Besides, it supports shielding of event logging by event domain, helping you to evaluate the impact of event logging. HiSysEvent provides event logging APIs for OpenHarmony to record important information of key processes during system running. Besides, it supports shielding of event logging by event domain, helping you to evaluate the impact of event logging.
### Working Principles ### Working Principles
Before logging system events, you need to complete HiSysEvent logging configuration. For details, see [HiSysEvent Logging Configuration](subsys-dfx-hisysevent-logging-config.md). Before logging system events, you need to configure HiSysEvent logging. For details, see [HiSysEvent Logging Configuration](subsys-dfx-hisysevent-logging-config.md).
## How to Develop ## How to Develop
### Use Cases ### Use Cases
Use HiSysEvent logging to flush logged event data to disks. Use HiSysEvent logging to flush logged event data to the event file.
### Available APIs ### Available APIs
#### C++ Event Logging APIs #### C++ Event Logging API
HiSysEvent logging is implemented using the API provided by the **HiSysEvent** class. For details, see the API Reference. HiSysEvent logging is implemented using the API provided by the **HiSysEvent** class. For details, see the [API Header Files](/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent/include/).
> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE** > **NOTE**
> >
> In OpenHarmony-3.2-Beta3, HiSysEvent logging is open for restricted use to avoid event storms. The **HiSysEvent::Write** API in Table 1 is replaced by the **HiSysEventWrite** API in Table 2. The **HiSysEvent::Write** API has been deprecated. Use the **HiSysEventWrite** API instead for HiSysEvent logging. > In OpenHarmony-3.2-Beta3, HiSysEvent logging is open for restricted use to avoid event storms. The **HiSysEvent::Write** API in Table 1 is replaced by the **HiSysEventWrite** API in Table 2. The **HiSysEvent::Write** API has been deprecated. Use the **HiSysEventWrite** API instead for HiSysEvent logging.
**Table 1** C++ event logging API (deprecated) **Table 1** Description of the C++ event logging API (deprecated)
| API | Description | | API | Description |
| ------------------------------------------------------------ | ---------------------- | | ------------------------------------------------------------ | --------------------- |
| template&lt;typename... Types&gt; <br>static int Write(const std::string &amp;domain, const std::string &amp;eventName, EventType type, Types... keyValues) | Flushes logged event data to disks.| | template&lt;typename...&nbsp;Types&gt;&nbsp;<br>static&nbsp;int&nbsp;Write(const&nbsp;std::string&nbsp;&amp;domain,&nbsp;const&nbsp;std::string&nbsp;&amp;eventName,&nbsp;EventType&nbsp;type,&nbsp;Types...&nbsp;keyValues) | Flushes logged event data to the event file.|
**Table 2** C++ event logging API (in use) **Table 2** Description of the C++ event logging API (in use)
| API | Description |
| ------------------------------------------------------------ | ---------------------- |
| HiSysEventWrite(domain, eventName, type, ...) | Flushes logged event data to disks.|
**Table 3** Event types
| API | Description | | API | Description |
| --------- | ------------ | | ------------------------------------------------------------ | --------------------- |
| FAULT | Fault event| | HiSysEventWrite(domain, eventName, type, ...) | Flushes logged event data to the event file.|
| STATISTIC | Statistical event|
| SECURITY | Security event| **Table 3** Description of EventType enums
| BEHAVIOR | Behavior event|
| Event Type | Description |
| --------- | ----------- |
| FAULT | Fault event.|
| STATISTIC | Statistical event.|
| SECURITY | Security event.|
| BEHAVIOR | Behavior event.|
#### C Event Logging API
HiSysEvent logging is implemented using the API provided in the following table. For details, see the [API Header Files](/base/hiviewdfx/hisysevent/interfaces/native/innerkits/hisysevent/include/).
**Table 4** Description of the C event logging API
| API | Description |
| ------------------------------------------------------------ | ------------------------ |
| int OH_HiSysEvent_Write(const char\* domain, const char\* name, HiSysEventEventType type, HiSysEventParam params[], size_t size); | Flushes logged event data to the event file.|
**Table 5** Description of HiSysEventEventType enums
| Event Type | Description |
| -------------------- | -------------- |
| HISYSEVENT_FAULT | Fault event.|
| HISYSEVENT_STATISTIC | Statistical event.|
| HISYSEVENT_SECURITY | Security event.|
| HISYSEVENT_BEHAVIOR | Behavior event.|
**Table 6** Description of the HiSysEventParam structure
| Attribute | Type | Description |
| --------- | -------------------- | ---------------------------------- |
| name | char name[] | Event parameter name. |
| t | HiSysEventParamType | Event parameter type. |
| v | HiSysEventParamValue | Event parameter value. |
| arraySize | size_t | Array length when the event parameter value is of the array type.|
**Table 7** Description of HiSysEventParamType enums
| Type | Description |
| ----------------------- | -------------------------- |
| HISYSEVENT_INVALID | Invalid event parameter. |
| HISYSEVENT_BOOL | Event parameter of the bool type. |
| HISYSEVENT_INT8 | Event parameter of the int8_t type. |
| HISYSEVENT_UINT8 | Event parameter of the uint8_t type. |
| HISYSEVENT_INT16 | Event parameter of the int16_t type. |
| HISYSEVENT_UINT16 | Event parameter of the uint16_t type. |
| HISYSEVENT_INT32 | Event parameter of the int32_t type. |
| HISYSEVENT_UINT32 | Event parameter of the uint32_t type. |
| HISYSEVENT_INT64 | Event parameter of the int64_t type. |
| HISYSEVENT_UINT64 | Event parameter of the uint64_t type. |
| HISYSEVENT_FLOAT | Event parameter of the float type. |
| HISYSEVENT_DOUBLE | Event parameter of the double type. |
| HISYSEVENT_STRING | Event parameter of the char* type. |
| HISYSEVENT_BOOL_ARRAY | Event parameter of the bool array type. |
| HISYSEVENT_INT8_ARRAY | Event parameter of the int8_t array type. |
| HISYSEVENT_UINT8_ARRAY | Event parameter of the uint8_t array type. |
| HISYSEVENT_INT16_ARRAY | Event parameter of the int16_t array type. |
| HISYSEVENT_UINT16_ARRAY | Event parameter of the uint16_t array type.|
| HISYSEVENT_INT32_ARRAY | Event parameter of the int32_t array type. |
| HISYSEVENT_UINT32_ARRAY | Event parameter of the uint32_t array type.|
| HISYSEVENT_INT64_ARRAY | Event parameter of the int64_t array type. |
| HISYSEVENT_UINT64_ARRAY | Event parameter of the uint64_t array type.|
| HISYSEVENT_FLOAT_ARRAY | Event parameter of the float array type. |
| HISYSEVENT_DOUBLE_ARRAY | Event parameter of the double array type. |
| HISYSEVENT_STRING_ARRAY | Event parameter of the char* array type. |
**Table 8** Description of the HiSysEventParamValue union
| Attribute| Type| Description |
| -------- | -------- | ------------------------ |
| b | bool | Event parameter value of the bool type. |
| i8 | int8_t | Event parameter value of the int8_t type. |
| ui8 | uint8_t | Event parameter value of the uint8_t type. |
| i16 | int16_t | Event parameter value of the int16_t type. |
| ui16 | uint16_t | Event parameter value of the uint16_t type.|
| i32 | int32_t | Event parameter value of the int32_t type. |
| ui32 | uint32_t | Event parameter value of the uint32_t type.|
| i64 | int64_t | Event parameter value of the int64_t type. |
| ui64 | uint64_t | Event parameter value of the uint64_t type.|
| f | float | Event parameter value of the float type. |
| d | double | Event parameter value of the double type. |
| s | char* | Event parameter value of the char* type. |
| array | void* | Event parameter value of the array type. |
#### Kernel Event Logging APIs #### Kernel Event Logging APIs
The following table describes the kernel event logging APIs. Kernel event logging is implemented using the APIs provided in the following table. For details, see the [API Header File](/kernel/linux/linux-5.10/include/dfx/hiview_hisysevent.h).
**Table 4** Kernel event logging APIs **Table 9** Description of kernel event logging APIs
| API | Description | | API | Description |
| ------------------------------------------------------------ | ------------------------------------ | | ------------------------------------------------------------ | ----------------------------------- |
| struct hiview_hisysevent *hisysevent_create(const char *domain, const char *name, enum hisysevent_type type); | Creates a **hisysevent** object. | | struct hiview_hisysevent *hisysevent_create(const char *domain, const char *name, enum hisysevent_type type); | Creates a **hisysevent** object. |
| void hisysevent_destroy(struct hiview_hisysevent *event); | Destroys a **hisysevent** object. | | void hisysevent_destroy(struct hiview_hisysevent *event); | Destroys a **hisysevent** object. |
| int hisysevent_put_integer(struct hiview_hisysevent *event, const char *key, long long value); | Adds event parameters of the integer type to a **hisysevent** object. | | int hisysevent_put_integer(struct hiview_hisysevent *event, const char *key, long long value); | Adds event parameters of the integer type to a **hisysevent** object. |
| int hisysevent_put_string(struct hiview_hisysevent *event, const char *key, const char *value); | Adds event parameters of the string type to a **hisysevent** object.| | int hisysevent_put_string(struct hiview_hisysevent *event, const char *key, const char *value); | Adds event parameters of the string type to a **hisysevent** object.|
| int hisysevent_write(struct hiview_hisysevent *event); | Flushes **hisysevent** object data to disks. | | int hisysevent_write(struct hiview_hisysevent *event); | Flushes **hisysevent** object data to the event file. |
**Table 5** Kernel event types **Table 10** Description of hisysevent_type enums
| API | Description | | Event Type | Description |
| --------- | ------------ | | --------- | ----------- |
| FAULT | Fault event| | FAULT | Fault event.|
| STATISTIC | Statistical event| | STATISTIC | Statistical event.|
| SECURITY | Security event| | SECURITY | Security event.|
| BEHAVIOR | Behavior event| | BEHAVIOR | Behavior event.|
### How to Develop ### How to Develop
#### C++ Event Logging #### C++ Event Logging
1. Call the event logging API wherever needed, with required event parameters passed to the API. Call the event logging API wherever needed, with required event parameters passed to the API.
```c++ ```c++
HiSysEventWrite(HiSysEvent::Domain::AAFWK, "START_APP", HiSysEvent::EventType::BEHAVIOR, "APP_NAME", "com.ohos.demo"); HiSysEventWrite(HiSysEvent::Domain::AAFWK, "START_APP", HiSysEvent::EventType::BEHAVIOR, "APP_NAME", "com.ohos.demo");
``` ```
#### C Event Logging
1. If you want to pass custom event parameters to the event logging API, create an event parameter object based on the event parameter type and add the object to the event parameter array.
```c
// Create an event parameter of the int32_t type.
HiSysEventParam param1 = {
.name = "KEY_INT32",
.t = HISYSEVENT_INT32,
.v = { .i32 = 1 },
.arraySize = 0,
};
// Create an event parameter of the int32_t array type.
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]),
};
// Add the event parameter object to the created event parameter array.
HiSysEventParam params[] = { param1, param2 };
```
2. Call the event logging API wherever needed, with required event parameters passed to the API.
```c
OH_HiSysEvent_Write("TEST_DOMAIN", "TEST_NAME", HISYSEVENT_BEHAVIOR, params, sizeof(params) / sizeof(params[0]));
```
#### Kernel Event Logging #### Kernel Event Logging
1. Create a **hisysevent** object based on the specified event domain, event name, and event type. 1. Create a **hisysevent** object based on the specified event domain, event name, and event type.
...@@ -151,7 +260,7 @@ Assume that a service module needs to trigger event logging during application s ...@@ -151,7 +260,7 @@ Assume that a service module needs to trigger event logging during application s
external_deps = [ "hisysevent_native:libhisysevent" ] external_deps = [ "hisysevent_native:libhisysevent" ]
``` ```
2. In the application startup function **StartAbility()** of the service module, call the event logging API with the event parameters passed in. 2. In the application startup function **StartAbility()** of the service module, call the event logging API with event parameters passed in.
```c++ ```c++
#include "hisysevent.h" #include "hisysevent.h"
...@@ -164,6 +273,37 @@ Assume that a service module needs to trigger event logging during application s ...@@ -164,6 +273,37 @@ Assume that a service module needs to trigger event logging during application s
} }
``` ```
#### C Event Logging
Assume that a service module needs to trigger event logging during application startup to record the application startup event and application bundle name. The following is the complete sample code:
1. Add the HiSysEvent component dependency to the **BUILD.gn** file of the service module.
```c++
external_deps = [ "hisysevent_native:libhisysevent" ]
```
2. In the application startup function **StartAbility()** of the service module, call the event logging API with event parameters passed in.
```c
#include "hisysevent_c.h"
int StartAbility()
{
... // Other service logic
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]));
... // Other service logic
}
```
#### Kernel Event Logging #### Kernel Event Logging
Assume that the kernel service module needs to trigger event logging during device startup to record the device startup event. The following is the complete sample code: Assume that the kernel service module needs to trigger event logging during device startup to record the device startup event. The following is the complete sample code:
...@@ -200,11 +340,10 @@ Assume that the kernel service module needs to trigger event logging during devi ...@@ -200,11 +340,10 @@ Assume that the kernel service module needs to trigger event logging during devi
} }
``` ```
#### Shielding of Event Logging by Event Domain #### Shielding of Event Logging by Event Domain
- If you want to shield event logging for the **AAFWK** and **POWER** domains in a **.cpp** file, define the **DOMAIN_MASKS** macro before including the **hisysevent.h** header file to the **.cpp** file. - If you want to shield event logging for the **AAFWK** and **POWER** domains in a **.cpp** file, define the **DOMAIN_MASKS** macro before including the **hisysevent.h** header file to the **.cpp** file.
```c++ ```c++
#define DOMAIN_MASKS "AAFWK|POWER" #define DOMAIN_MASKS "AAFWK|POWER"
#include "hisysevent.h" #include "hisysevent.h"
...@@ -212,14 +351,13 @@ Assume that the kernel service module needs to trigger event logging during devi ...@@ -212,14 +351,13 @@ Assume that the kernel service module needs to trigger event logging during devi
HiSysEventWrite(OHOS:HiviewDFX::HiSysEvent::Domain::AAFWK, "JS_ERROR", OHOS:HiviewDFX::HiSysEvent::EventType::FAULT, "MODULE", "com.ohos.module"); // HiSysEvent logging is not performed. HiSysEventWrite(OHOS:HiviewDFX::HiSysEvent::Domain::AAFWK, "JS_ERROR", OHOS:HiviewDFX::HiSysEvent::EventType::FAULT, "MODULE", "com.ohos.module"); // HiSysEvent logging is not performed.
... // Other service logic ... // Other service logic
HiSysEventWrite(OHOS:HiviewDFX::HiSysEvent::Domain::POWER, "POWER_RUNNINGLOCK", OHOS:HiviewDFX::HiSysEvent::EventType::FAULT, "NAME", "com.ohos.module"); // HiSysEvent logging is not performed. HiSysEventWrite(OHOS:HiviewDFX::HiSysEvent::Domain::POWER, "POWER_RUNNINGLOCK", OHOS:HiviewDFX::HiSysEvent::EventType::FAULT, "NAME", "com.ohos.module"); // HiSysEvent logging is not performed.
``` ```
- If you want to shield event logging for the **AAFWK** and **POWER** domains of the entire service module, define the **DOMAIN_MASKS** macro as follows in the **BUILG.gn** file of the service module. - If you want to shield event logging for the **AAFWK** and **POWER** domains of the entire service module, define the **DOMAIN_MASKS** macro as follows in the **BUILG.gn** file of the service module.
```gn ```gn
config("module_a") { config("module_a") {
... // Other configuration items ... // Other configuration items
cflags_cc += ["-DDOMAIN_MASKS=\"AAFWK|POWER\""] cflags_cc += ["-DDOMAIN_MASKS=\"AAFWK|POWER\""]
} }
``` ```
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或