**HiSysEvent****打点**

HiSysEvent**打点**

一、概述

1、功能简介

HiSysEvent打点提供了事件埋点功能，开发者可以通过在关键路径埋点来记录系统在运行过程中的重要信息。同时，HiSysEvent打点也提供了以事件领域为单位的HiSysEvent打点屏蔽机制，方便开发者评估及调试HiSysEvent打点操作的影响。

2、运作机制

在进行HiSysEvent事件埋点之前，需要先完成HiSysEvent打点配置，具体配置方法请参考https://docs.openharmony.cn/pages/v3.2Beta/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md/

二、接口说明

1、c++事件埋点API接口功能介绍

接口名	描述
template<typename… Types> static int Write(const std::string &domain, const std::string &eventName, EventType type, Types… keyValues)	将打点事件数据进行落盘

2、c++事件类型API接口介绍

接口名	描述
FAULT	故障类型事件
STATISTIC	统计类型事件
SECURITY	安全类型事件
BEHAVIOR	行为类型事件

三、HiSysEvent打点配置

1、在进行HiSysEvent事件埋点之前，需要先完成HiSysEvent打点配置

组件若有HiSysEvent事件的打点需求，则需要先定义yaml文件并在bundle.js文件中配置yaml文件的路径。OpenHarmony编译框架在编译过程中则会通过python编译脚本解析校验bundle.js文件指定的所有yaml文件。在解析校验之后，编译框架会将这些yaml文件中配置的信息汇总转换成名为hisysevent.def的json文件。最后，将此json文件打包到系统指定路径下，用作HiSysEvent事件落盘的判断依据。

2、置HiSysEvent打点之前，开发者应了解以下基本概念：

概念	描述
事件领域	用于标识事件所属的领域，在yaml文件中以domain为键值指定
事件名称	用于指定事件领域包含的所有事件
参数	用于定义某个事件名称包含的所有键值

3、约束与限制

定义事件领域、事件名称及参数的约束与限制：

l s

l 每个事件领域可定义零个或多个事件名称，同一个事件领域内部的事件名称不能重名。

l 每个事件名称可定义多个参数，同一个事件名称内部的参数不能重名，每个事件名称有且只有一个名称为__BASE的参数，此参数字段组成如表1，其它自定义参数，具体字段组成如表2。

表1 __BASE参数字段说明

字段名称	描述
type	字段说明：必选字段，用来标识该事件名称的类型。<br/> 取值范围：<br/>- FAULT：错误类型。<br/>- STATISTIC：统计类型。<br/>- SECURITY：安全性。<br/>- BEHAVIOR：用户行为。
level	字段说明：必选字段，用来标识该事件名称的级别。<br/> 取值范围：<br/>- CRITICAL：严重。<br/>- MINOR：一般。
tag	字段说明：可选字段，用来标识该事件名称的标签。<br/> 定义规则：<br/>-最多可同时定义5个标签，标签之间使用空格来分隔。<br/>-单个标签最多包含16个字符，字符范围[a-zA-Z0-9]
desc	字段说明：必选字段，用来对该事件名称进行描述。<br/> 定义规则：<br/>-至少包含3个字符，最多包含128个字符，字符范围[a-zA-Z0-9 _]

表2 自定义参数字段说明

字段名称	描述
type	字段说明：必选字段，用来标识该参数的类型。<br/> 取值范围：<br/>- BOOL<br/>- UINT8<br/>- UINT16<br/>- INT32<br/>- UINT32<br/>- UINT64<br/>- FLOAT<br/>- DOUBLE<br/>- STRING
arrsize	字段作用：可选字段，用来标识数组类型参数的长度。<br/> 取值范围：<br/>- 1~100
desc	字段作用：必选字段，用来对该参数进行描述。<br/> 定义规则：<br/>-至少包含3个字符，最多包含128个字符，字符范围[a-zA-Z0-9 _]

4、编写yaml文件

l 事件领域命名规则：

字母开头，且只能由大写字母/数字/下划线组成；

字符串长度取值范围为1~16。

l 事件名称命名规则：

字母开头，且只能由大写字母/数字/下划线组成；

字符串长度取值范围1~32；

单个事件领域内部事件名称的不能超过4096个。

l 参数命名规则：

字母开头，且只能由大写字母/数字/下划线组成；

字符串长度取值范围1~32；

单个事件名称内包含的参数的个数不能超过128个。

5、验证yaml文件

配置yaml文件路径

在bundle.js文件中通过hisysevent_config属性完成yaml文件的路径指定：

yaml文件可根据实际需求置于组件工程的任意目录下，只要在bundle.js文件指定即可。

全量编译整个系统，会将所有组件配置的yaml文件中的配置进行汇总，正常完成系统编译后，指定目录下就会生成hisysevent.def文件。

四、C++点开发

在需要埋点的地方直接调用埋点接口，并传入相应事件参数即可：

五、查询定义的事件

可以“hisysevent -l”命令查询历史HiSysEvent事件，确认触发的自定义HiSysEvent事件是否打点成功。