• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# HiSysEvent Logging Configuration
2
3
4## Overview
5
6
7### Function Introduction
8
9If HiSysEvent logging is required for a component, you need to define a YAML file and [configure the YAML file path](#verifying-the-yaml-file) in the **bundle.json** file. During compilation, the OpenHarmony compilation framework will use the Python compilation script to parse and verify all the YAML files configured in the **bundle.json** file. On completion, the compilation framework will summarize the configuration information in the YAML files and convert the information into a JSON file named **hisysevent.def**. After that, the compilation framework will put the JSON file to a specified path as the basis for the system to determine whether to log system events.
10
11
12### Basic Concepts
13
14Understanding the following concepts would be helpful for you in configuring HiSysEvent logging.
15
16- Event domain<br>Represents the domain to which an event belongs. It is specified by the **domain** field in the YAML file. For details, see [domain](#writing-a-yaml-file) in the example YAML file.
17
18- Event name<br>Indicates the events in an event domain. For details, see [EVENT\_NAMEA/EVENT\_NAMEB](#writing-a-yaml-file) in the example YAML file.
19
20- Parameter<br>Defines the key values in an event name. For details, see [__BASE/NAME1/NAME2](#writing-a-yaml-file) in the example YAML file.
21
22
23### Constraints
24
25Constraints on the event domain, event name, and parameter
26
27- Each YAML file can contain only one event domain, and the domain name cannot be the same as that defined in other YAML files.
28
29- Zero or more event names can be defined for one event domain. The event names in the same event domain must be unique.
30
31- Multiple parameters can be defined for one event name. The parameters in the same event name must be unique. There must be only one parameter named **__BASE** in each event name. See Table 1 for the fields of this parameter and Table 2 for the fields of other custom parameters.
32
33    **Table 1** Fields in the \__BASE parameter
34
35  | Field| Description|
36  | -------- | -------- |
37  | type | Event type. This field is mandatory.<br>Value:<br>- FAULT: fault<br>- STATISTIC: statistics<br>- SECURITY: security<br>- BEHAVIOR: user behavior|
38  | level | Event level. This field is mandatory.<br>Value:<br>- CRITICAL: critical<br>- MINOR: minor|
39  | tag | Event tag. This field is mandatory.<br>Rule:<br>- You can define a maximum of five tags, separated with a space.<br>- A single tag can contain a maximum of 16 characters, including a to z, A to Z, and 0 to 9.|
40  | desc | Event name. This field is mandatory.<br>Rule:<br>The description contains 3 to 128 characters, including a to z, A to Z, 0 to 9, and underscores (_).|
41
42    **Table 2** Description of custom parameters
43
44  | Field| Description|
45  | -------- | -------- |
46  | type | Parameter type. This field is mandatory.<br>Value:<br>- BOOL<br>- INT8<br>- UINT8<br>- INT16<br>- UINT16<br>- INT32<br>- UINT32<br>- INT64<br>- UINT64<br>- FLOAT<br>- DOUBLE<br>- STRING |
47  | arrsize | Length of the parameter of the array type. This field is optional.<br>Value:<br>1-100|
48  | desc | Parameter description. This field is mandatory.<br>Rule:<br>The description contains 3 to 128 characters, including a to z, A to Z, 0 to 9, and underscores (_).|
49
50## How to Develop
51
52### Writing a YAML File
53
54
55**Writing Rules**
56
57- Event domain naming rules:
58  - The name must start with a letter and can contain only uppercase letters, digits, and underscores (&#95;).
59  - The name contains 1 to 16 characters.
60
61- Event naming rules:
62  - The name must start with a letter and can contain only uppercase letters, digits, and underscores (&#95;).
63  - The name contains 1 to 32 characters.
64  - The number of internal event names in an event domain cannot exceed 4096.
65
66- Parameter naming rules:
67  - The name must start with a letter and can contain only uppercase letters, digits, and underscores (&#95;).
68  - The name contains 1 to 48 characters.
69  - The number of parameters in an event domain cannot exceed 128.
70
71
72**Example**
73
74- In the example YAML file, the event domain name is **MODULEA**. The event domain contains two events named **EVENT_NAMEA** and **EVENT_NAMEB**.
75
76- **EVENT\_NAMEA** is defined as a critical event of the fault type. The event contains the **NAME1** parameter of the string type, the **NAME2** parameter of the string type, and the **NAME3** parameter of the unsigned short integer type. Therefore, you can perform [real-time subscription](../subsystems/subsys-dfx-hisysevent-listening.md) to the event based on the event domain **MODULEA** and event name **EVENT\_NAMEA**.
77
78- **EVENT\_NAMEB** is defined as a general event of the statistics type. The event contains the **NAME1** parameter of the unsigned short integer type and the **NAME2** parameter of the integer type. Because two event tags named **tag1** and **tag2** are defined for **EVENT\_NAMEB** in the **\__BASE** parameter, you can perform [real-time subscription](../subsystems/subsys-dfx-hisysevent-listening.md) to the event based on the event domain **MODULEA** and event name **EVENT\_NAMEB**, or based on the event tag.
79
80  ```
81  ##########################################
82  # the hisysevent definition for module a #
83  ##########################################
84
85  domain: MODULEA
86
87  EVENT_NAMEA:
88      __BASE: {type: FAULT, level: CRITICAL, desc: event name a}
89      NAME1: {type: STRING, desc: name1}
90      NAME2: {type: STRING, desc: name2}
91      NAME3: {type: UINT16, desc: name3}
92
93  EVENT_NAMEB:
94      __BASE: {type: STATISTIC, level: MINOR, tag: tag1 tag2, desc: event name b}
95      NAME1: {type: UINT16, desc: name1}
96      NAME2: {type: INT32, desc: name2}
97  ```
98
99
100### Verifying the YAML File
101
102
103**Configuring the YAML File Path**
104
105In the **bundle.json** file, use the **hisysevent_config** attribute to specify the YAML file path.
106
107
108```
109{
110    "name": "@ohos/moduel_a",
111    "description": "module a",
112    "version": "3.1",
113    "license": "Apache License 2.0",
114    "publishAs": "code-segment",
115    "segment": {
116        "destPath": "moduel_a_path"
117    },
118    "dirs": {},
119    "scripts": {},
120    "component": {
121        "name": "hisysevent_native",
122        "subsystem": "hiviewdfx",
123        "adapted_system_type": [
124            "standard"
125        ],
126        "rom": "",
127        "ram": "",
128        "hisysevent_config": [
129            "//moduel_a_path/yaml_file1.yaml",
130            "//moduel_a_path/yaml_file2.yaml"
131        ],
132        "deps": {
133            "components": [
134                "hilog_native",
135                "hitrace_native",
136                "ipc",
137                "safwk",
138                "samgr",
139                "utils_base"
140            ],
141            "third_party": []
142        },
143        "build": {
144        }
145    }
146}
147```
148
149
150> **NOTE**<br>
151> The YAML file can be placed in any directory of the component project as needed. You only need to specify the path in the **bundle.json** file.
152
153
154**Compiling YAML Files**
155
156- Perform full compilation.
157  - During full compilation of the system, the configurations in the YAML files of all components are summarized. After the compilation is complete, the **hisysevent.def** file will be generated in the specified directory.
158
159     ```
160     cd *absolute path of the project's root directory*
161     ./build --product-name <product name>
162     ```
163
164  - To obtain the **hisysevent.def** file generated after full compilation, run the following commands:
165
166     ```
167     cd absolute path of the project's root directory
168     find out -name hisysevent.def -type f
169     ```
170
171- Single-file compilation:
172  You can also compile the YAML file of a single component by running the following commands:
173
174
175  ```
176  cd absolute path of the project's root directory
177  ./build/ohos/hisysevent/gen_def_from_all_yaml.py --yaml-list <yaml file list> --def-path <file store directory>
178  ```
179
180    **Table 3** Parameters for single-file compilation
181
182  | Option| Description|
183  | -------- | -------- |
184  | --yaml-list | Paths of the YAML files to be compiled. If there are multiple YAML file paths, separate each of them with a space.|
185  | --def-path | Path of the **hisysevent.def** file generated after compilation.|
186
187
188### Logging and Querying Events
189
1901. Push the **hisysevent.def** file to the **/system/etc/hiview/** directory of the device by using the [hdc_std tool](../subsystems/subsys-toolchain-hdc-guide.md).
191
1922. Trigger logging of the custom system events in the YAML file. Then, run [hisysevent -l](../subsystems/subsys-dfx-hisysevent-tool.md) to query historical system events to find out if the logging of the custom system events is successful.
193