diff --git a/zh-cn/device-dev/subsystems/figures/Hiview_module_data_interaction.png b/zh-cn/device-dev/subsystems/figures/Hiview_module_data_interaction.png new file mode 100644 index 0000000000000000000000000000000000000000..87f67eef3f467d7ac59f2a877ae0e3ac8bb84c07 Binary files /dev/null and b/zh-cn/device-dev/subsystems/figures/Hiview_module_data_interaction.png differ diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging.md b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging.md index 7a846893cd99a3525b9bc0eb17573aa9bd41081e..db570a79071efe3eaff95bcf249cda3ac2c94f5f 100644 --- a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging.md +++ b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging.md @@ -1,106 +1,167 @@ # HiSysEvent打点 - ## 概述 - ### 功能简介 -HiSysEvent提供OpenHarmony打点接口，通过在关键路径打点记录系统在运行过程中的重要信息，辅助开发者定位问题，此外还支持开发者将数据上传到云进行大数据质量度量。 - +HiSysEvent打点提供了事件埋点功能，开发者可以通过在关键路径埋点来记录系统在运行过程中的重要信息。 -### 约束与限制 - -在进行HiSysEvent事件打点之前，需要先完成HiSysEvent打点配置，具体配置方法请参考[《HiSysEvent打点配置指导》](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md)。 +### 运作机制 +在进行HiSysEvent事件埋点之前，需要先完成HiSysEvent打点配置，具体配置方法请参考[《HiSysEvent打点配置指导》](https://gitee.com/openharmony/docs/blob/master/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md)。 ## 开发指导 +### 场景介绍 + +事件埋点的主要工作是将打点数据进行落盘。 ### 接口说明 -C++打点接口如下： - -HiSysEvent类，具体的API详见接口文档 。 - - **表4** HiSysEvent接口介绍 - -| 接口名 | 描述 | -| -------- | -------- | -| template<typename... Types> static int Write(const std::string &domain,
 const std::string &eventName,
 EventType type, Types... keyValues) | 接口功能：记录系统事件。
输入参数：
- domain：事件的相关领域，需要使用预置领域请参考Domain，可自定义领域。自定义领域长度在16个字符以内，有效的字符是0-9、A-Z，以字母开头。
- eventName：事件名，长度在32个字符以内，有效的字符是0-9、A-Z、下划线，以字母开头，不能以下划线结尾。
- type：事件类型，参考EventType。
- keyValues：事件参数键值对，支持基本的数据类型、std::string，以及std::vector<基本类型>、std:vector<std::string>。参数名长度在48个字符以内，有效的字符是0-9、A-Z、下划线，以字母开头，不能以下划线结尾。参数名的个数在32个以内。
返回值：
- 0：系统事件记录成功。
- 负值：系统事件记录失败。 | - - **表5** HiSysEvent::Domain接口介绍 - -| 成员名称 | 描述 | -| -------- | -------- | -| static const std::string AAFWK | 元能力子系统 | -| static const std::string APPEXECFWK | 用户程序框架子系统 | -| static const std::string ACCOUNT | 账号子系统 | -| static const std::string ARKUI | ARKUI子系统 | -| static const std::string AI | AI业务子系统 | -| static const std::string BARRIER_FREE | 无障碍软件服务子系统 | -| static const std::string BIOMETRICS | 生物特征识别服务子系统 | -| static const std::string CCRUNTIME | C/C++运行环境子系统 | -| static const std::string COMMUNICATION | 公共通信子系统 | -| static const std::string DEVELOPTOOLS | 研发工具链子系统 | -| static const std::string DISTRIBUTED_DATAMGR | 分布式数据管理子系统 | -| static const std::string DISTRIBUTED_SCHEDULE | 分布式任务调度子系统 | -| static const std::string GLOBAL | 全球化子系统 | -| static const std::string GRAPHIC | 图形子系统 | -| static const std::string HIVIEWDFX | DFX子系统 | -| static const std::string IAWARE | 本地资源调度管控子系统 | -| static const std::string INTELLI_ACCESSORIES | 智能配件业务子系统 | -| static const std::string INTELLI_TV | 智能电视业务子系统 | -| static const std::string IVI_HARDWARE | 车机专有硬件服务子系统 | -| static const std::string LOCATION | 位置服务子系统 | -| static const std::string MSDP | 综合传感处理平台子系统 | -| static const std::string MULTI_MEDIA | 媒体子系统 | -| static const std::string MULTI_MODAL_INPUT | 多模输入子系统 | -| static const std::string NOTIFICATION | 事件通知子系统 | -| static const std::string POWERMGR | 电源服务子系统 | -| static const std::string ROUTER | 路由器业务子系统 | -| static const std::string SECURITY | 安全子系统 | -| static const std::string SENSORS | 泛Sensor服务子系统 | -| static const std::string SOURCE_CODE_TRANSFORMER | 应用移植子系统 | -| static const std::string STARTUP | 启动恢复子系统 | -| static const std::string TELEPHONY | 电话服务子系统 | -| static const std::string UPDATE | 升级服务子系统 | -| static const std::string USB | USB服务子系统 | -| static const std::string WEARABLE_HARDWARE | 穿戴专有硬件服务子系统 | -| static const std::string WEARABLE_HARDWARE | 穿戴业务子系统 | -| static const std::string OTHERS | 其它 | - - **表6** HiSysEvent::EventType接口介绍 - -| 接口名 | 描述 | -| -------- | -------- | -| FAULT | 故障类型事件 | -| STATISTIC | 统计类型事件 | -| SECURITY | 安全类型事件 | -| BEHAVIOR | 系统行为事件 | +#### c++接口说明 +c++事件埋点开发能力如下：HiSysEvent类，具体的API详见接口文档 。 -### 开发实例 +**表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 | 行为类型事件 | + +#### kernel接口说明 + +kernel事件埋点开发能力如下： + +**表3** kernel事件埋点API接口功能介绍 -C++接口实例 +| 接口名 | 描述 | +| ------------------------------------------------------------ | ------------------------------------ | +| struct hiview_hisysevent *hisysevent_create(const char *domain, const char *name, enum hisysevent_type type); | 创建一个事件对象 | +| void hisysevent_destroy(struct hiview_hisysevent *event); | 销毁一个事件对象 | +| int hisysevent_put_integer(struct hiview_hisysevent *event, const char *key, long long value); | 将整数类型的事件参数添加到事件对象 | +| int hisysevent_put_string(struct hiview_hisysevent *event, const char *key, const char *value); | 将字符串类型的事件参数添加到事件对象 | +| int hisysevent_write(struct hiview_hisysevent *event); | 将事件对象数据进行落盘 | -1. 源代码开发 - 在类定义头文件或者类实现源文件中，包含HiSysEvent头文件： +**表4** kernel事件类型API接口介绍 - +| 接口名 | 描述 | +| --------- | ------------ | +| FAULT | 故障类型事件 | +| STATISTIC | 统计类型事件 | +| SECURITY | 安全类型事件 | +| BEHAVIOR | 行为类型事件 | + +### 开发步骤 + +#### c++埋点开发步骤 + +1. 在需要埋点的地方直接调用埋点接口，并传入相应事件参数即可： + + ```c++ + HiSysEvent::Write(HiSysEvent::Domain::AAFWK, "START_APP", HiSysEvent::EventType::BEHAVIOR, "APP_NAME", "com.ohos.demo"); ``` - #include "hisysevent.h" + +#### kernel埋点开发步骤 + +1. 根据事件领域、事件名称、事件类型参数，创建一个基础的事件对象： + + ```c + struct hiview_hisysevent *event = hisysevent_create("KERNEL", "BOOT", BEHAVIOR); ``` - 假设在业务关注应用启动时间start_app，在业务类实现相关源文件中使用（调用接口打点）： +2. 将自定义的事件参数，传入到事件对象里： + + ```c + // 添加整数类型参数 + hisysevent_put_integer(event, "BOOT_TIME", 100); - + // 添加字符串类型参数 + hisysevent_put_string(event, "MSG", "This is a test message"); ``` - HiSysEvent::Write(HiSysEvent::Domain::AAFWK, "start_app", HiSysEvent::EventType::FAULT, "app_name", "com.demo"); + +3. 在事件对象构建完成后，将事件进行上报： + + ```c + hisysevent_write(event); ``` -2. 编译设置，在BUILD.gn里增加子系统SDK依赖： - +4. 事件上报完成后，需要手动将对象销毁： + + ```c + hisysevent_destroy(&event); ``` + +### 开发实例 + +#### c++埋点开发实例 + +假设业务模块需要在应用启动时进行埋点来记录应用启动事件，且需要记录应用的包名信息，完整使用示例如下所示： + +1. 首先，需要在业务模块的在BUILD.gn里增加HiSysEvent部件依赖： + + ```c++ external_deps = [ "hisysevent_native:libhisysevent" ] ``` + +2. 在业务模块的应用启动函数StartAbility()中，调用埋点接口并传入对应事件参数： + + + ```c++ + #include "hisysevent.h" + + int StartAbility() + { + ... // 其他业务逻辑 + int ret = HiSysEvent::Write(HiSysEvent::Domain::AAFWK, "START_APP", HiSysEvent::EventType::BEHAVIOR, "APP_NAME", "com.ohos.demo"); + ... // 其他业务逻辑 + } + ``` + +#### kernel埋点开发实例 + +假设内核业务模块需要在设备启动时进行埋点来记录设备启动事件，完整使用示例如下所示： + +1. 在设备启动函数device_boot()中，构建一个启动事件对象，然后将事件进行上报，最后销毁事件对象。 + +```c +#include + +#include +#include + +int device_boot() +{ + ... // 其他业务逻辑 + struct hiview_hisysevent *event = NULL; + int ret = 0; + + event = hisysevent_create("KERNEL", "BOOT", BEHAVIOR); + if (!event) { + pr_err("failed to create event"); + return -EINVAL; + } + ret = hisysevent_put_string(event, "MSG", "This is a test message"); + if (ret != 0) { + pr_err("failed to put sting to event, ret=%d", ret); + goto hisysevent_end; + } + ret = hisysevent_write(event); + +hisysevent_end: + hisysevent_destroy(&event); + ... // 其他业务逻辑 +} +``` + +# 参考 + +HiSysEvent模块会将埋点数据写入到节点文件中，而埋点数据的解析处理会在Hiview模块中统一进行，详细处理过程可参考[Hiview开发指导](subsys-dfx-hiview.md)。 diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-overview.md b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..2203d06a22e87162f34e7e17d5042b1741cd883e --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-overview.md @@ -0,0 +1,22 @@ +# HiSysEvent概述 + + +## 概述 + +HiSysEvent是面向OpenHarmony系统开发者提供的系统打点功能，通过在关键路径埋点来记录系统在运行过程中的重要信息，辅助开发者定位问题，此外还支持开发者将打点数据上传到云进行大数据质量度量。 + +HiSysEvent提供给开发者的打点相关能力主要包括事件配置、事件埋点、事件订阅、事件查询以及事件调试工具，各模块能力介绍如下： + +- 事件配置：提供了事件的yaml配置能力，支持在yaml文件中对HiSysEvent事件进行定义。 + +- 事件埋点：提供了事件埋点的相关接口能力，支持对打点的HiSysEvent事件进行落盘。 + +- 事件订阅：提供了事件订阅的相关接口能力，支持根据事件领域和事件名称来对HiSysEvent事件进行订阅。 + +- 事件查询：提供了事件查询的相关接口能力，支持根据事件领域和事件名称来对HiSysEvent事件进行查询。 + +- 事件调试工具：提供了hisysevent工具，支持通过该工具来实时订阅HiSysEvent事件及查询历史HiSysEvent事件。 + +## 参考 + +如果您想了解更多关于HiSysEvent特性的源码及使用信息，请参考[HiSysEvent代码仓](https://gitee.com/openharmony/hiviewdfx_hisysevent)。 \ No newline at end of file diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent.md b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent.md index 189134220d756e0355c9f049d79834fd8d033197..8b1ac55fa90fcb9faa55b2038ed3e45d097b39c0 100644 --- a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent.md +++ b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent.md @@ -2,6 +2,8 @@ +- **[HiSysEvent概述](subsys-dfx-hisysevent-overview.md)** + - **[HiSysEvent打点配置](subsys-dfx-hisysevent-logging-config.md)** - **[HiSysEvent打点](subsys-dfx-hisysevent-logging.md)** diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-hiview.md b/zh-cn/device-dev/subsystems/subsys-dfx-hiview.md new file mode 100644 index 0000000000000000000000000000000000000000..30e6f3fe4cb4b4cd079b819b5bb7ab1fc31015ff --- /dev/null +++ b/zh-cn/device-dev/subsystems/subsys-dfx-hiview.md @@ -0,0 +1,197 @@ +# Hiview开发指导 + + +## 概述 + + +### 功能简介 + +Hiview是一个跨平台的终端设备维测服务集，由插件管理平台和基于平台上运行的服务插件来构成整套系统。Hiview维测服务是由HiSysEvent事件驱动的，其核心为分布在系统各处的HiSysEvent桩点，格式化的事件会通过HiSysEvent打点API上报至Hiview进行处理，其处理流程如下图所示： + +**图1** Hiview模块数据交互图 + +![Hiview_module_data_interaction](figures/Hiview_module_data_interaction.png) + +1. 业务进程通过调用HiSysEvent模块提供的打点接口，上报打点事件信息并将其写入节点文件。 +2. Hiview进程中的SysEventSource事件源会从节点中异步读取出事件信息，并将事件分发到SysEventPipeline流水线上进行处理，其中： + - SysEventService插件负责对事件进行校验及落盘； + - Faultlogger插件负责处理故障相关事件； + - EventLogger插件负责采集事件相关的日志信息。 +3. 在流水线上完成事件处理后，还会把事件发送到平台订阅事件队列里，然后将事件派发到订阅插件进行处理，其中： + - FreezeDetectorPlugin插件负责处理冻屏相关事件； + - HiCollieCollector插件负责卡死相关事件。 + +### 基本概念 + +在进行Hiview的开发前，开发者应了解以下基本概念： + +- 插件 + + 运行在Hiview进程中，随Hiview二进制一同交付的完成独立功能的维测、故障管理模块，具有编译时可独立拆解、运行时寄宿于平台、动态配置等特性。 + +- 流水线 + + 事件处理插件的有序集合，进入流水线的事件会按序经过流水线上的每个插件处理。 + +- 事件源 + + 一种能够生产事件的特殊插件，相较普通插件，需要能够绑定流水线、生产事件并将事件分发给流水线。 + +- 流水线组 + + 配置在相同事件源的多个流水线被称作一个流水线组。 + +### 运作机制 + +Hiview支持基于插件管理平台的插件开发，提供了插件开发的相关能力，开发者可以通过在Hiview平台上新增自己的插件，来对HiSysEvent事件进行特定业务处理。在进行插件开发前，开发者应该了解插件的相关运作原理。 + +#### 插件注册 + +插件的注册方式有三种： + +| 名称 | 说明 | +| ------------------ | ------------------------------------------------------------ | +| 静态注册 | 通过使用宏定义REGISTER(xxx);注册，该种注册方式的插件不能被卸载 | +| 代理注册 | 通过使用宏定义REGISTER_PROXY(xxx);注册，开机不加载运行时动态加载卸载 | +| 代理注册且开机加载 | 通过使用宏定义REGISTER_PROXY_WITH_LOADED(xxx);注册，开机加载之后再动态卸载加载 | + +#### 插件驱动 + +插件的事件驱动有两种方式——流水线驱动和订阅驱动，区别如下： + +- 流水线驱动的插件需要配置在流水线上，当事件从事件源分发到流水线后，会按序流转到流水线上配置的每个插件进行处理。 +- 订阅驱动的插件无需配置在流水线上，但是需要在插件启动时注册一个监听者到Hiview平台，并且插件本身需要实现事件监听处理函数。 + +#### 插件包加载 + +根据业务的需求，插件可以不用全部编译在Hiview二进制中。 + +Hiview支持将多个插件编译成为一个独立的插件包，以独立so的形式预置到系统中，并且一个so需要对应于一个plugin_config文件，例如libxxx.z.so，对应于xxx_plugin_config配置文件。Hiview进程在启动时，会扫描系统中的插件包so以及对应的配置文件，并对插件包中实现的插件进行加载。 + +对插件包做如下补充说明： + +1. 插件包作为一个独立的个体在插件管理平台中运行，内部插件、流水线或者事件源都与在Hiview二进制中的插件没有功能上的差异。 + +2. 插件包中的插件可以插入到Hiview二进制中的流水线中。 + + +3. 无论在何处的订阅者，根据其订阅的规则都可以收到全平台发送出来的相应事件。 + + +## 插件开发指导 + + +### 场景介绍 + +当开发者需要对事件源分发过来的HiSysEvent事件进行特定业务处理的时候，需要在Hiview平台上新增一个插件，并借助该插件进行相应业务处理，下文将具体介绍如何进行Hiview插件开发。 + +### 接口说明 + +插件开发的相关接口如下，具体的API详见接口文档。 + +**表1** Plugin类API接口功能介绍 + +| 接口名 | 描述 | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| virtual void OnLoad() | 插件加载函数，当插件被平台加载后调用，可以用于初始化一些数据 | +| virtual void OnUnload() | 插件卸载函数，当插件被平台卸载前调用，可以用于回收一些数据 | +| virtual bool ReadyToLoad() | 用于在Hiview启动加载插件时判断当前插件能否被加载 | +| virtual bool OnEvent(std::shared_ptr\& event) | 事件处理函数，用于接收处理流水线或者平台分发过来的事件并进行业务处理 | +| virtual bool CanProcessEvent(std::shared_ptr\ event) | 用于判断事件是否能向后流转整条流水线（当插件位于流水线上的第一个时生效） | +| HiviewContext* GetHiviewContext() | 获取Hiview插件管理平台的上下文对象 | + +**表2** Event类API接口功能介绍 + +| 接口名 | 描述 | +| ---------------------- | ---------------------------- | +| domain_ | 事件领域 | +| eventName_ | 事件名称 | +| happenTime_ | 事件发生时间 | +| jsonExtraInfo_ | Json格式的事件数据 | +| bool IsPipelineEvent() | 判断事件是否为流水线事件 | +| bool HasFinish() | 判断事件是否还能继续往后流转 | + +### 开发步骤 + +1. 首先，需要定义一个继承自Plugin基类的业务插件类： + + ```c++ + #include "event.h" + #include "plugin.h" + + class PluginExample : public Plugin { + public: + bool OnEvent(std::shared_ptr& event) override; + void OnLoad() override; + void OnUnload() override; + }; + ``` + +2. 然后，在插件类实现代码中，需要先对插件进行注册，再根据业务需要覆写实现相应的函数。 + + ```c++ + #include "plugin_factory.h" + + // 静态注册插件 + REGISTER(PluginExample); + + void PluginExample::OnLoad() + { + ... // 在插件加载时，可以进行插件的资源初始化工作 + printf("PluginExample OnLoad \n"); + } + + void PluginExample::OnUnload() + { + ... // 在插件卸载时，可以进行插件的资源释放工作 + printf("PluginExample OnUnload \n"); + } + + bool PluginExample::OnEvent(std::shared_ptr& event) + { + ... // 在事件处理函数中，可以进行对事件进行特定业务处理 + printf("PluginExample OnEvent \n"); + + // 例如，插件只关注某个领域的事件，并需要将这个领域的事件信息进行日志打印处理 + if (event->domain_ == "TEST_DOMAIN") { + printf("The event data received is %s \n", event->jsonExtraInfo_); + return true; + } + + return false; + } + ``` + +3. 最后，需要将插件配置在plugin_build.json文件中，随Hiview二进制一同编译： + + ```json + { + "plugins": { + "PluginExample": { + "path": "plugins/PluginExample", + "name": "PluginExample" + } + }, + "rules": [ + { + "info": { + "loadorder": { + "PluginExample": { + "loadtime": 0 + } + }, + "pipelines": { + "SysEventPipeline": [ + PluginExample + ] + } + } + } + ] + } + ``` + + +## 参考 + +如果您想了解更多关于Hiview特性的源码及使用信息，请参考[Hiview代码仓](https://gitee.com/openharmony/hiviewdfx_hiview)。 \ No newline at end of file diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-overview.md b/zh-cn/device-dev/subsystems/subsys-dfx-overview.md index ad4e2455326eacf4e828ab91e63775d564e46b66..6f258b47c5f8a1ca074ebf3252efbceb3c8a5381 100755 --- a/zh-cn/device-dev/subsystems/subsys-dfx-overview.md +++ b/zh-cn/device-dev/subsystems/subsys-dfx-overview.md @@ -21,6 +21,8 @@ - Faultlogger崩溃故障检测，标准系统类设备（参考内存≥128MB）适用。 +- Hiview插件平台，标准系统类设备（参考内存≥128MB）适用。 + ## 基本概念 diff --git a/zh-cn/device-dev/subsystems/subsys-dfx.md b/zh-cn/device-dev/subsystems/subsys-dfx.md index b8ea56af1cd9448804682fad904e1705780e5bd5..e0c14d76beed5857eb773ab53e71bc650df24bec 100644 --- a/zh-cn/device-dev/subsystems/subsys-dfx.md +++ b/zh-cn/device-dev/subsystems/subsys-dfx.md @@ -9,4 +9,5 @@ - **[HiCollie开发指导](subsys-dfx-hicollie.md)** - **[HiSysEvent开发指导](subsys-dfx-hisysevent.md)** - **[HiDumper开发指导](subsys-dfx-hidumper.md)** -- **[HiChecker开发指导](subsys-dfx-hichecker.md)** \ No newline at end of file +- **[HiChecker开发指导](subsys-dfx-hichecker.md)** +- **[Hiview开发指导](subsys-dfx-hiview.md)**