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 zip file named **hisysevent.zip**. After that, the compilation framework will put the zip 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    **Table 1** Fields in the \__BASE parameter
33
34  | Field| Description|
35  | -------- | -------- |
36  | type | Event type. This field is mandatory.<br>Value:<br>- **FAULT**: fault<br>- STATISTIC: statistics<br>- **SECURITY**: security<br>- **BEHAVIOR**: behavior|
37  | level | Event level. This field is mandatory.<br>Value:<br>- CRITICAL: critical<br>- MINOR: minor|
38  | 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.|
39  | desc | Event name. This field is mandatory.<br>Rule:<br>-  A string of 3 to 128 characters.|
40  | preserve | Whether events need to be logged in the event file. This field is optional. The default value is **true**.<br>Value:<br>- **true**: Events need to be logged in the event file.<br>- **false**: Events do not need to be logged in the event file.|
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>-  A string of 3 to 128 characters.|
49
50
51## How to Develop
52
53
54### Writing a YAML File
55
56
57**Writing Rules**
58
59- Event domain naming rules:
60  - The name must start with a letter and can contain only uppercase letters, digits, and underscores (&#95;).
61  - The name contains 1 to 16 characters.
62
63- Event naming rules:
64  - The name must start with a letter and can contain only uppercase letters, digits, and underscores (&#95;).
65  - The name contains 1 to 32 characters.
66  - The number of internal event names in an event domain cannot exceed 4096.
67
68- Parameter naming rules:
69  - The name must start with a letter and can contain only uppercase letters, digits, and underscores (&#95;).
70  - The name contains 1 to 48 characters.
71  - The number of parameters in an event domain cannot exceed 128.
72
73
74**Example**
75
76- In the example YAML file, the event domain name is **MODULEA**. The event domain contains two events named **EVENT_NAMEA** and **EVENT_NAMEB**.
77
78- **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**.
79
80- **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.
81
82  ```
83  ##########################################
84  # the hisysevent definition for module a #
85  ##########################################
86
87  domain: MODULEA
88
89  EVENT_NAMEA:
90      __BASE: {type: FAULT, level: CRITICAL, desc: event name a}
91      NAME1: {type: STRING, desc: name1}
92      NAME2: {type: STRING, desc: name2}
93      NAME3: {type: UINT16, desc: name3}
94
95  EVENT_NAMEB:
96      __BASE: {type: STATISTIC, level: MINOR, tag: tag1 tag2, desc: event name b}
97      NAME1: {type: UINT16, desc: name1}
98      NAME2: {type: INT32, desc: name2}
99  ```
100
101
102### Verifying the YAML File
103
104
105**Configuring the YAML File Path**
106
107In the **bundle.json** file, use the **hisysevent_config** attribute to specify the YAML file path.
108
109
110```
111{
112    "name": "@ohos/moduel_a",
113    "description": "module a",
114    "version": "3.1",
115    "license": "Apache License 2.0",
116    "publishAs": "code-segment",
117    "segment": {
118        "destPath": "moduel_a_path"
119    },
120    "dirs": {},
121    "scripts": {},
122    "component": {
123        "name": "hisysevent_native",
124        "subsystem": "hiviewdfx",
125        "adapted_system_type": [
126            "standard"
127        ],
128        "rom": "",
129        "ram": "",
130        "hisysevent_config": [
131            "//moduel_a_path/yaml_file1.yaml",
132            "//moduel_a_path/yaml_file2.yaml"
133        ],
134        "deps": {
135            "components": [
136                "hilog_native",
137                "hitrace_native",
138                "ipc",
139                "safwk",
140                "samgr",
141                "utils_base"
142            ],
143            "third_party": []
144        },
145        "build": {
146        }
147    }
148}
149```
150
151
152> **NOTE**<br>
153> 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.
154
155
156**Compiling YAML Files**
157
158- Perform full compilation.
159  - During full compilation of the system, the configurations in the YAML files of all components are summarized. After the compilation is complete, the **hisysevent.zip** file will be generated in the specified directory.
160
161     ```
162     cd *absolute path of the project's root directory*
163     ./build --product-name <product name>
164     ```
165
166  - To obtain the **hisysevent.zip** file generated after full compilation, run the following commands:
167
168     ```
169     cd *absolute path of the project's root directory*
170     find out -name hisysevent.zip -type f
171     ```
172
173- Single-file compilation:
174  You can also compile the YAML file of a single component by running the following commands:
175
176
177  ```
178  cd absolute path of the project's root directory
179  ./build/ohos/hisysevent/gen_def_from_all_yaml.py --yaml-list <yaml file list> --def-path <file store directory>
180  ```
181
182    **Table 3** Parameters for single-file compilation
183
184  | Option| Description|
185  | -------- | -------- |
186  | --yaml-list | Paths of the YAML files to be compiled. If there are multiple YAML file paths, separate each of them with a space.|
187  | --def-path | Path of the **hisysevent.zip** file generated after compilation.|
188
189
190### Logging and Querying Events
191
1921. Decompress the **hisysevent.zip** file to obtain the **hisysevent.def** file, and then use the [hdc_std tool](../subsystems/subsys-toolchain-hdc-guide.md) to push the file to the **/data/system/hiview/unzip_configs/sys_event_def/** directory of the device.
193
1942. 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.
195