@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

参数：

错误码：

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

示例：

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

参数：

返回值：

错误码：

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

示例：

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

hiAppEvent.configure

configure(config: ConfigOption): void

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

错误码：

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

示例：

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

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

ConfigOption

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

hiAppEvent.addWatcher

addWatcher(watcher: Watcher): AppEventPackageHolder

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

返回值：

错误码：

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

示例：

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

参数：

错误码：

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

示例：

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

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

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

Watcher

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

TriggerCondition

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

AppEventFilter

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

AppEventPackageHolder

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

constructor

constructor(watcherName: string)

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

示例：

let holder = hiAppEvent.addWatcher({
    name: "watcher",
});

setSize

setSize(size: number): void

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

参数：

错误码：

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

示例：

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

hiAppEvent.clearData

clearData(): void

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

示例：

hiAppEvent.clearData();

EventType

事件类型枚举。

系统能力： SystemCapability.HiviewDFX.HiAppEvent

event

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent

param

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

系统能力： SystemCapability.HiviewDFX.HiAppEvent