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

joytrian
发布于 2023-4-7 16:10
浏览
0收藏

版本:v3.1 Beta

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

更新时间: 2023-02-17 09:19


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


说明

本模块首批接口从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.

示例:

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

​AppEventInfo​

应用事件对象。

返回值:

类型

说明

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

事件领域。

name

string

事件名称。

eventType

​EventType​

事件类型。

params

object

事件参数。

hiAppEvent.configure

configure(config: ​​ConfigOption​​): void

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

系统能力: SystemCapability.HiviewDFX.HiAppEvent

参数:

参数名

类型

必填

说明

config

​ConfigOption​

应用事件打点配置项对象。

错误码:

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

错误码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

​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: 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

​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

​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 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

行为类型事件。

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。


文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-hiviewdfx-hiappevent-0000001478341401-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001478341401__导入模块​

已于2023-4-7 16:10:56修改
收藏
回复
举报
回复
    相关推荐