1# HiSysEvent打点配置指导<a name="ZH-CN_TOPIC_0000001080478132"></a> 2 3## 概述<a name="section315316685115"></a> 4 5组件若有HiSysEvent事件的打点需求，则需要先定义yaml文件并在bundle.js文件中[配置yaml文件的路径](#section123181432175135)。OpenHarmony编译框架在编译过程中则会通过python编译脚本解析校验bundle.js文件指定的所有yaml文件。在解析校验之后，编译框架会将这些yaml文件中配置的信息汇总转换成名为hisysevent.def的json文件。最后，将此json文件打包到系统指定路径下，用作HiSysEvent事件落盘的判断依据。 6 7### 基本概念<a name="section123181432175143"></a> 8 9在配置HiSysEvent打点之前，开发者应了解以下基本概念： 10 11- 事件领域 12 用于标识事件所属的领域，在yaml文件中以domain为键值指定，可参考yaml文件样例中的[domain](#section123181432175123)。 13 14- 事件名称 15 用于指定事件领域包含的所有事件，可参考yaml文件样例中的[EVENT_NAMEA/EVENT_NAMEB](#section123181432175123)。 16 17- 参数 18 用于定义某个事件名称包含的所有键值，可参考yaml文件样例中的[__BASE/NAME1/NAME2](#section123181432175123)。 19 20 21### 约束与限制<a name="section123181432175114"></a> 22 23**定义事件领域、事件名称及参数的约束与限制：** 24 25- 每个yaml文件只能有一个事件领域，且不能与其他yaml文件中定义的事件领域重名。 26 27- 每个事件领域可定义零个或多个事件名称，同一个事件领域内部的事件名称不能重名。 28 29- 每个事件名称可定义多个参数，同一个事件名称内部的参数不能重名，每个事件名称**有且只有**一个名称为__BASE的参数，此参数字段组成如表1，其它自定义参数，具体字段组成如表2。 30 31 **表 1** __BASE参数字段说明 32 33 | 字段名称 | 描述 | 34 | ----- | ----- | 35 | type | 字段说明：必选字段，用来标识该事件名称的类型。<br><br>取值范围：<ul><li>FAULT：错误类型。</li><li>STATISTIC：统计类型。</li><li>SECURITY：安全性。</li><li>BEHAVIOR：用户行为。</li></ul> | 36 | level | 字段说明：必选字段，用来标识该事件名称的级别。<br><br>取值范围：<ul><li>CRITICAL：严重。</li><li>MINOR：一般。</li></ul> | 37 | tag | 字段说明：可选字段，用来标识该事件名称的标签。<br><br>定义规则：<ul><li>最多可同时定义5个标签，标签之间使用空格来分隔。</li><li>单个标签最多包含16个字符，字符范围[a-zA-Z0-9]</li></ul> | 38 | desc | 字段说明：必选字段，用来对该事件名称进行描述。<br><br>定义规则：<ul><li>至少包含3个字符，最多包含128个字符，字符范围[a-zA-Z0-9 _]</li></ul> | 39 40 **表 2** 自定义参数字段说明 41 42 | 字段名称 | 描述 | 43 | ----- | ----- | 44 | type | 字段说明：必选字段，用来标识该参数的类型。<br><br>取值范围：<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> | 45 | arrsize | 字段作用：可选字段，用来标识数组类型参数的长度。<br><br>取值范围：<ul><li>1~100</li></ul> | 46 | desc | 字段作用：必选字段，用来对该参数进行描述。<br><br>定义规则：<ul><li>至少包含3个字符，最多包含128个字符，字符范围[a-zA-Z0-9 _]</li></ul> | 47 48## 编写yaml文件<a name="section123181432175113"></a> 49 50### yaml文件编写规则<a name="section123181432175133"></a> 51 52- 事件领域命名规则： 53 - 字母开头，且只能由大写字母/数字/下划线组成； 54 - 字符串长度取值范围为1~16。 55- 事件名称命名规则： 56 - 字母开头，且只能由大写字母/数字/下划线组成； 57 - 字符串长度取值范围1~32； 58 - 单个事件领域内部事件名称的不能超过4096个。 59- 参数命名规则： 60 - 字母开头，且只能由大写字母/数字/下划线组成； 61 - 字符串长度取值范围1~32； 62 - 单个事件名称内包含的参数的个数不能超过128个。 63 64### yaml文件编写样例<a name="section123181432175123"></a> 65 66- yaml文件样例指定的事件领域名称为MODULEA，该事件领域包含两个事件，名称分别是EVENT_NAMEA和EVENT_NAMEB。 67- EVENT_NAMEA被定义成错误类型的严重事件，该事件包含类型为字符串类型的NAME1参数、字符串类型的NAME2参数及无符号短整型类型的NAME3参数，可以通过事件领域MODULEA和事件名称EVENT_NAMEA对其进行[实时订阅](subsys-dfx-hisysevent-listening.md)。 68- EVENT_NAMEB被定义成统计类型的一般事件，EVENT_NAMEB包含类型为无符号短整型类型的NAME1参数及整型类型的NAME2参数。因为EVENT_NAMEB在__BASE参数中定义了名称为tag1和tag2的两个事件标签，所以不仅可以通过事件领域MODULEA和事件名称EVENT_NAMEB对其进行[实时订阅](subsys-dfx-hisysevent-listening.md)，，所以还可以通过事件标签对该事件进行[实时订阅](subsys-dfx-hisysevent-listening.md)。 69 70 ``` 71 ########################################## 72 # the hisysevent definition for module a # 73 ########################################## 74 75 domain: MODULEA 76 77 EVENT_NAMEA: 78 __BASE: {type: FAULT, level: CRITICAL, desc: event name a} 79 NAME1: {type: STRING, desc: name1} 80 NAME2: {type: STRING, desc: name2} 81 NAME3: {type: UINT16, desc: name3} 82 83 EVENT_NAMEB: 84 __BASE: {type: STATISTIC, level: MINOR, tag: tag1 tag2, desc: event name b} 85 NAME1: {type: UINT16, desc: name1} 86 NAME2: {type: INT32, desc: name2} 87 ``` 88 89## 验证yaml文件<a name="section123181432175115"></a> 90 91### 配置yaml文件路径<a name="section123181432175135"></a> 92 93在bundle.js文件中通过```hisysevent_config```属性完成yaml文件的路径指定： 94 95``` 96{ 97 "name": "@ohos/moduel_a", 98 "description": "module a", 99 "version": "3.1", 100 "license": "Apache License 2.0", 101 "publishAs": "code-segment", 102 "segment": { 103 "destPath": "moduel_a_path" 104 }, 105 "dirs": {}, 106 "scripts": {}, 107 "component": { 108 "name": "hisysevent_native", 109 "subsystem": "hiviewdfx", 110 "adapted_system_type": [ 111 "standard" 112 ], 113 "rom": "", 114 "ram": "", 115 "hisysevent_config": [ 116 "//moduel_a_path/yaml_file1.yaml", 117 "//moduel_a_path/yaml_file2.yaml" 118 ], 119 "deps": { 120 "components": [ 121 "hilog_native", 122 "hitrace_native", 123 "ipc", 124 "safwk", 125 "samgr_standard", 126 "utils_base" 127 ], 128 "third_party": [] 129 }, 130 "build": { 131 } 132 } 133} 134``` 135 136> **说明：** 137>yaml文件可根据实际需求置于组件工程的任意目录下，只要在bundle.js文件指定即可。 138 139### 编译yaml文件<a name="section123181432175137"></a> 140 141- 全量编译： 142 143 - 全量编译整个系统，会将所有组件配置的yaml文件中的配置进行汇总，正常完成系统编译后，指定目录下就会生成hisysevent.def文件。 144 145 ``` 146 cd 工程根目录的绝对路径 147 ./build --product-name <product name> 148 ``` 149 150 - 全量编译生成的hisysevent.def文件可以通过以下命令获取： 151 152 ``` 153 cd 工程根目录的绝对路径 154 find out -name hisysevent.def -type f 155 ``` 156 157- 单文件编译： 158 159 也可以只编译单个组件的yaml文件，命令如下： 160 161 ``` 162 cd 工程根目录的绝对路径 163 ./build/ohos/hisysevent/gen_def_from_all_yaml.py --yaml-list <yaml file list> --def-path <file store directory> 164 ``` 165 166 **表 3** 单文件编译参数说明 167 168 | 选项名称 | 描述 | 169 | ------ | ------ | 170 | --yaml-list | 指定需要编译的yaml文件路径列表，多个yaml文件路径之间用空格分隔。 | 171 | --def-path | 指定编译生成的hisysevent.def文件的生成路径。 | 172 173### 打点及查询定义的事件<a name="section123181432175139"></a> 174 1751. 通过[hdc_std工具](subsys-toolchain-hdc-guide.md)将hisysevent.def文件推送到至设备的//system/etc/hiview/目录下; 176 1772. 触发yaml文件自定义的HiSysEvent事件完成打点，通过[hisysevent -l](subsys-dfx-hisysevent-tool.md)命令查询历史HiSysEvent事件，确认触发的自定义HiSysEvent事件是否打点成功。 178
