harmony 鸿蒙@ohos.hiviewdfx.hiAppEvent (应用事件打点)

  • 2022-10-28
  • 浏览 (725)

@ohos.hiviewdfx.hiAppEvent (应用事件打点)

本模块提供了应用事件打点能力，包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。

说明：

本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

导入模块

import hiAppEvent from '@ohos.hiviewdfx.hiAppEvent';

hiAppEvent.write

write(info: AppEventInfo, callback: AsyncCallback<void>): void

应用事件打点方法，将事件写入到当天的事件文件中，可接收AppEventInfo类型的事件对象，使用callback方式作为异步回调。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名 类型 必填 说明
info AppEventInfo 是 应用事件对象。
callback AsyncCallback<void> 是 打点回调函数。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码ID 错误信息
11100001 Function is disabled.
11101001 Invalid event domain.
11101002 Invalid event name.
11101003 Invalid number of event parameters.
11101004 Invalid string length of the event parameter.
11101005 Invalid event parameter name.
11101006 Invalid array length of the event parameter.

示例：

import { BusinessError } from '@ohos.base';

let eventParams: Record<string, number|string> = {
  "int_data": 100,
  "str_data": "strValue",
};
hiAppEvent.write({
  domain: "test_domain",
  name: "test_event",
  eventType: hiAppEvent.EventType.FAULT,
  params: eventParams,
}, (err: BusinessError) => {
  if (err) {
    console.error(`code: ${err.code}, message: ${err.message}`);
    return;
  }
  console.log(`success to write event`);
});

hiAppEvent.write

write(info: AppEventInfo): Promise&lt;void&gt;

应用事件打点方法，将事件写入到当天的事件文件中，可接收AppEventInfo类型的事件对象，使用Promise方式作为异步回调。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名 类型 必填 说明
info AppEventInfo 是 应用事件对象。

返回值：

类型 说明
Promise&lt;void&gt; Promise对象。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码ID 错误信息
11100001 Function is disabled.
11101001 Invalid event domain.
11101002 Invalid event name.
11101003 Invalid number of event parameters.
11101004 Invalid string length of the event parameter.
11101005 Invalid event parameter name.
11101006 Invalid array length of the event parameter.

示例：

import { BusinessError } from '@ohos.base';

let eventParams: Record<string, number|string> = {
  "int_data": 100,
  "str_data": "strValue",
};
hiAppEvent.write({
  domain: "test_domain",
  name: "test_event",
  eventType: hiAppEvent.EventType.FAULT,
  params: eventParams,
}).then(() => {
  console.log(`success to write event`);
}).catch((err: BusinessError) => {
  console.error(`code: ${err.code}, message: ${err.message}`);
});

AppEventInfo

此接口提供了应用事件信息的参数选项。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称 类型 必填 说明
domain string 是 事件领域。事件领域名称支持数字、小写字母、下划线字符，需要以小写字母开头且不能以下划线结尾，长度非空且不超过16个字符。
name string 是 事件名称。事件名称支持数字字符、字母字符、下划线字符，需要以字母字符或$字符开头且不能以下划线字符结尾，长度非空且不超过48个字符。
eventType EventType 是 事件类型。
params object 是 事件参数对象，每个事件参数包括参数名和参数值，其规格定义如下：
- 参数名为string类型，只支持数字字符、字母字符、下划线字符，需要以字母字符或$字符开头且不能以下划线字符结尾，长度非空且不超过16个字符。
- 参数值支持string、number、boolean、数组类型，string类型参数长度需在8*1024个字符以内，超出会做丢弃处理；number类型参数取值需在Number.MIN_SAFE_INTEGER~Number.MAX_SAFE_INTEGER范围内，超出可能会产生不确定值；数组类型参数中的元素类型只能全为string、number、boolean中的一种，且元素个数需在100以内，超出会做丢弃处理。
- 参数个数需在32个以内，超出的参数会做丢弃处理。

hiAppEvent.configure

configure(config: ConfigOption): void

应用事件打点配置方法，可用于配置打点开关、目录存储配额大小等功能。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名 类型 必填 说明
config ConfigOption 是 应用事件打点配置项对象。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码ID 错误信息
11103001 Invalid max storage quota value.

示例：

// 配置打点开关为关闭状态
let config1: hiAppEvent.ConfigOption = {
  disable: true,
};
hiAppEvent.configure(config1);

// 配置文件目录存储配额为100M
let config2: hiAppEvent.ConfigOption = {
  maxStorage: '100M',
};
hiAppEvent.configure(config2);

ConfigOption

此接口提供了对应用事件打点功能的配置选项。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称 类型 必填 说明
disable boolean 否 打点功能开关，默认值为false。true：关闭打点功能，false：不关闭打点功能。
maxStorage string 否 打点数据存放目录的配额大小，默认值为“10M”。
在目录大小超出配额后，下次打点会触发对目录的清理操作：按从旧到新的顺序逐个删除打点数据文件，直到目录大小不超出配额时结束。

hiAppEvent.addWatcher

addWatcher(watcher: Watcher): AppEventPackageHolder

添加应用事件观察者方法，可用于订阅应用事件。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名 类型 必填 说明
watcher Watcher 是 应用事件观察者。

返回值：

类型 说明
AppEventPackageHolder 订阅数据持有者，订阅失败时返回null。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码ID 错误信息
11102001 Invalid watcher name.
11102002 Invalid filtering event domain.
11102003 Invalid row value.
11102004 Invalid size value.
11102005 Invalid timeout value.

示例：

// 1. 如果观察者传入了回调的相关参数，则可以选择在自动触发的回调函数中对订阅事件进行处理
hiAppEvent.addWatcher({
  name: "watcher1",
  appEventFilters: [
    {
      domain: "test_domain",
      eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR]
    }
  ],
  triggerCondition: {
    row: 10,
    size: 1000,
    timeOut: 1
  },
  onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => {
    if (holder == null) {
      console.error("holder is null");
      return;
    }
    console.info(`curRow=${curRow}, curSize=${curSize}`);
    let eventPkg: hiAppEvent.AppEventPackage|null = null;
    while ((eventPkg = holder.takeNext()) != null) {
      console.info(`eventPkg.packageId=${eventPkg.packageId}`);
      console.info(`eventPkg.row=${eventPkg.row}`);
      console.info(`eventPkg.size=${eventPkg.size}`);
      for (const eventInfo of eventPkg.data) {
        console.info(`eventPkg.data=${eventInfo}`);
      }
    }
  }
});

// 2. 如果观察者未传入回调的相关参数，则可以选择使用返回的holder对象手动去处理订阅事件
let holder = hiAppEvent.addWatcher({
  name: "watcher2",
});
if (holder != null) {
  let eventPkg: hiAppEvent.AppEventPackage|null = null;
  while ((eventPkg = holder.takeNext()) != null) {
    console.info(`eventPkg.packageId=${eventPkg.packageId}`);
    console.info(`eventPkg.row=${eventPkg.row}`);
    console.info(`eventPkg.size=${eventPkg.size}`);
    for (const eventInfo of eventPkg.data) {
      console.info(`eventPkg.data=${eventInfo}`);
    }
  }
}

hiAppEvent.removeWatcher

removeWatcher(watcher: Watcher): void

移除应用事件观察者方法，可用于取消订阅应用事件。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名 类型 必填 说明
watcher Watcher 是 应用事件观察者。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码ID 错误信息
11102001 Invalid watcher name.

示例：

// 1. 定义一个应用事件观察者
let watcher: hiAppEvent.Watcher = {
  name: "watcher1",
}

// 2. 添加一个应用事件观察者来订阅事件
hiAppEvent.addWatcher(watcher);

// 3. 移除该应用事件观察者以取消订阅事件
hiAppEvent.removeWatcher(watcher);

Watcher

此接口提供了应用事件观察者的参数选项。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称 类型 必填 说明
name string 是 观察者名称，用于唯一标识观察者。
triggerCondition TriggerCondition 否 订阅回调触发条件，需要与回调函数一同传入才会生效。
appEventFilters AppEventFilter[] 否 订阅过滤条件，在需要对订阅事件进行过滤时传入。
onTrigger (curRow: number, curSize: number, holder: AppEventPackageHolder) => void 否 订阅回调函数，需要与回调触发条件一同传入才会生效，函数入参说明如下：
curRow：在本次回调触发时的订阅事件总数量；
curSize：在本次回调触发时的订阅事件总大小，单位为byte；
holder：订阅数据持有者对象，可以通过其对订阅事件进行处理。

TriggerCondition

此接口提供了回调触发条件的参数选项，只要满足任一条件就会触发订阅回调。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称 类型 必填 说明
row number 否 满足触发回调的事件总数量。
size number 否 满足触发回调的事件总大小，单位为byte。
timeOut number 否 满足触发回调的超时时长，单位为30s。

AppEventFilter

此接口提供了过滤应用事件的参数选项。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称 类型 必填 说明
domain string 是 需要订阅的事件领域。
eventTypes EventType[] 否 需要订阅的事件类型集合。

AppEventPackageHolder

订阅数据持有者类，用于对订阅事件进行处理。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

constructor

constructor(watcherName: string)

类构造函数，在添加应用事件观察者时，会由系统自动调用来创建一个该观察者对应的订阅数据持有者对象，并返回给开发者。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名 类型 必填 说明
watcherName string 是 观察者名称。

示例：

let holder1 = hiAppEvent.addWatcher({
    name: "watcher1",
});

setSize

setSize(size: number): void

设置每次取出的应用事件包的数据大小阈值。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

参数名 类型 必填 说明
size number 是 数据大小阈值，单位为byte，默认值为512*1024。

错误码：

以下错误码的详细介绍请参见应用事件打点错误码。

错误码ID 错误信息
11104001 Invalid size value.

示例：

let holder2 = hiAppEvent.addWatcher({
    name: "watcher2",
});
holder2.setSize(1000);

takeNext

takeNext(): AppEventPackage

根据设置的数据大小阈值来取出订阅事件数据，当订阅事件数据全部被取出时返回null作为标识。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

示例：

let holder3 = hiAppEvent.addWatcher({
    name: "watcher3",
});
let eventPkg = holder3.takeNext();

AppEventPackage

此接口提供了订阅返回的应用事件包的参数定义。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称 类型 必填 说明
packageId number 是 事件包ID，从0开始自动递增。
row number 是 事件包的事件数量。
size number 是 事件包的事件大小，单位为byte。
data string[] 是 事件包的事件信息。

hiAppEvent.clearData

clearData(): void

应用事件打点数据清理方法，将应用存储在本地的打点数据进行清除。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

示例：

hiAppEvent.clearData();

EventType

事件类型枚举。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称 值 说明
FAULT 1 故障类型事件。
STATISTIC 2 统计类型事件。
SECURITY 3 安全类型事件。
BEHAVIOR 4 行为类型事件。

event

此接口提供了所有预定义事件的事件名称常量。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称 类型 说明
USER_LOGIN string 用户登录事件。
USER_LOGOUT string 用户登出事件。
DISTRIBUTED_SERVICE_START string 分布式服务启动事件。

param

此接口提供了所有预定义参数的参数名称常量。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

名称 类型 说明
USER_ID string 用户自定义ID。
DISTRIBUTED_SERVICE_NAME string 分布式服务名称。
DISTRIBUTED_SERVICE_INSTANCE_ID string 分布式服务实例ID。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙接口

harmony 鸿蒙系统公共事件定义(待停用)

harmony 鸿蒙系统公共事件定义

harmony 鸿蒙开发说明

harmony 鸿蒙企业设备管理概述（仅对系统应用开放）

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager模块)

harmony 鸿蒙@ohos.distributedBundle (分布式包管理)

harmony 鸿蒙@ohos.bundle (Bundle模块)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (企业设备管理扩展能力)

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/e78bf76c7c7049b394cb322e16faa75a
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录