应用事件打点
本模块提供了应用事件打点能力,包括应用事件落盘、应用事件订阅、应用事件清理、打点功能配置等功能。
本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
hiAppEvent.write
write(info: AppEventInfo, callback: AsyncCallback<void>): void
应用事件打点方法,将事件写入到当天的事件文件中,可接收AppEventInfo类型的事件对象,使用callback方式作为异步回调。
系统能力: SystemCapability.HiviewDFX.HiAppEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
info | 是 | 应用事件对象。 | |
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. |
示例:
- hiAppEvent.write({
- domain: "test_domain",
- name: "test_event",
- eventType: hiAppEvent.EventType.FAULT,
- params: {
- int_data: 100,
- str_data: "strValue"
- }
- }, (err) => {
- if (err) {
- console.error(`code: ${err.code}, message: ${err.message}`);
- return;
- }
- console.log(`success to write event`);
- });
hiAppEvent.write
write(info: AppEventInfo): Promise<void>
应用事件打点方法,将事件写入到当天的事件文件中,可接收AppEventInfo类型的事件对象,使用Promise方式作为异步回调。
系统能力: SystemCapability.HiviewDFX.HiAppEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
info | 是 | 应用事件对象。 |
返回值:
类型 | 说明 |
---|---|
Promise<void> | 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. |
示例:
- hiAppEvent.write({
- domain: "test_domain",
- name: "test_event",
- eventType: hiAppEvent.EventType.FAULT,
- params: {
- int_data: 100,
- str_data: "strValue"
- }
- }).then(() => {
- console.log(`success to write event`);
- }).catch((err) => {
- console.error(`code: ${err.code}, message: ${err.message}`);
- });
AppEventInfo
此接口提供了应用事件信息的参数选项。
系统能力: SystemCapability.HiviewDFX.HiAppEvent
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
domain | string | 是 | 事件领域。事件领域名称支持数字、小写字母、下划线字符,需要以小写字母开头且不能以下划线结尾,长度非空且不超过16个字符。 |
name | string | 是 | 事件名称。事件名称支持数字、小写字母、下划线字符,需要以小写字母开头且不能以下划线结尾,长度非空且不超过48个字符。 |
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 | 是 | 应用事件打点配置项对象。 |
错误码:
以下错误码的详细介绍请参见应用事件打点错误码。
错误码ID | 错误信息 |
---|---|
11103001 | Invalid max storage quota value. |
示例:
- // 配置打点开关为关闭状态
- hiAppEvent.configure({
- disable: true
- });
- // 配置文件目录存储配额为100M
- hiAppEvent.configure({
- maxStorage: '100M'
- });
ConfigOption
此接口提供了对应用事件打点功能的配置选项。
系统能力: SystemCapability.HiviewDFX.HiAppEvent
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
disable | boolean | 否 | 打点功能开关,默认值为false。true:关闭打点功能,false:不关闭打点功能。 |
maxStorage | string | 否 | 打点数据存放目录的配额大小,默认值为“10M”。 在目录大小超出配额后,下次打点会触发对目录的清理操作:按从旧到新的顺序逐个删除打点数据文件,直到目录大小不超出配额时结束。 |
hiAppEvent.addWatcher
addWatcher(watcher: Watcher): AppEventPackageHolder
添加应用事件观察者方法,可用于订阅应用事件。
系统能力: SystemCapability.HiviewDFX.HiAppEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
watcher | 是 | 应用事件观察者。 |
返回值:
类型 | 说明 |
---|---|
订阅数据持有者,订阅失败时返回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: function (curRow, curSize, holder) {
- if (holder == null) {
- console.error("holder is null");
- return;
- }
- let eventPkg = 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 = 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 | 是 | 应用事件观察者。 |
错误码:
以下错误码的详细介绍请参见应用事件打点错误码。
错误码ID | 错误信息 |
---|---|
11102001 | Invalid watcher name. |
示例:
- // 1. 定义一个应用事件观察者
- let watcher = {
- name: "watcher1",
- }
- // 2. 添加一个应用事件观察者来订阅事件
- hiAppEvent.addWatcher(watcher);
- // 3. 移除该应用事件观察者以取消订阅事件
- hiAppEvent.removeWatcher(watcher);
Watcher
此接口提供了应用事件观察者的参数选项。
系统能力: SystemCapability.HiviewDFX.HiAppEvent
名称 | 类型 | 必填 | 说明 |
---|---|---|---|
name | string | 是 | 观察者名称,用于唯一标识观察者。 |
triggerCondition | 否 | 订阅回调触发条件,需要与回调函数一同传入才会生效。 | |
appEventFilters | 否 | 订阅过滤条件,在需要对订阅事件进行过滤时传入。 | |
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 | 否 | 需要订阅的事件类型集合。 |
constructor
constructor(watcherName: string)
类构造函数,在添加应用事件观察者时,会由系统自动调用来创建一个该观察者对应的订阅数据持有者对象,并返回给开发者。
系统能力: SystemCapability.HiviewDFX.HiAppEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
watcherName | string | 是 | 观察者名称。 |
示例:
- let holder = hiAppEvent.addWatcher({
- name: "watcher",
- });
setSize
setSize(size: number): void
设置每次取出的应用事件包的数据大小阈值。
系统能力: SystemCapability.HiviewDFX.HiAppEvent
参数:
参数名 | 类型 | 必填 | 说明 |
---|---|---|---|
size | number | 是 | 数据大小阈值,单位为byte,默认值为512*1024。 |
错误码:
以下错误码的详细介绍请参见应用事件打点错误码。
错误码ID | 错误信息 |
---|---|
11104001 | Invalid size value. |
示例:
- let holder = hiAppEvent.addWatcher({
- name: "watcher",
- });
- holder.setSize(1000);
takeNext
takeNext(): AppEventPackage
根据设置的数据大小阈值来取出订阅事件数据,当订阅事件数据全部被取出时返回null作为标识。
系统能力: SystemCapability.HiviewDFX.HiAppEvent
示例:
- let holder = hiAppEvent.addWatcher({
- name: "watcher",
- });
- let eventPkg = holder.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 | 行为类型事件。 |
更多建议: