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