@ohos.hiviewdfx.hiAppEvent (Application Event Logging)

The hiAppEvent module provides application event-related functions, including flushing application events to a disk, querying and clearing application events, and customizing application event logging configuration.

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

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

hiAppEvent.write

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

Writes events to the event file of the current day through AppEventInfo objects. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Error codes

For details about the error codes, see Application Event Logging Error Codes.

Example

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>

Writes events to the event file of the current day through AppEventInfo objects. This API uses a promise to return the result.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Return value

Error codes

For details about the error codes, see Application Event Logging Error Codes.

Example

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

Defines parameters for an AppEventInfo object.

System capability: SystemCapability.HiviewDFX.HiAppEvent

hiAppEvent.configure

configure(config: ConfigOption): void

Configures the application event logging function, such as setting the event logging switch and maximum size of the directory that stores the event logging files.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Error codes

For details about the error codes, see Application Event Logging Error Codes.

Example

// Disable the event logging function.
hiAppEvent.configure({
    disable: true
});

// Set the maximum size of the file storage directory to 100 MB.
hiAppEvent.configure({
    maxStorage: '100M'
});

ConfigOption

Configures options for application event logging.

System capability: SystemCapability.HiviewDFX.HiAppEvent

hiAppEvent.addWatcher

addWatcher(watcher: Watcher): AppEventPackageHolder

Adds a watcher to subscribe to application events.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Return value

Error codes

For details about the error codes, see Application Event Logging Error Codes.

Example

// 1. If callback parameters are passed to the watcher, you can have subscription events processed in the callback that is automatically triggered.
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. If no callback parameters are passed to the watcher, you can have subscription events processed manually through the subscription data 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

Removes a watcher to unsubscribe from application events.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Error codes

For details about the error codes, see Application Event Logging Error Codes.

Example

// 1. Define a watcher for application events.
let watcher = {
    name: "watcher1",
}

// 2. Add the watcher to subscribe to application events.
hiAppEvent.addWatcher(watcher);

// 3. Remove the watcher to unsubscribe from application events.
hiAppEvent.removeWatcher(watcher);

Watcher

Defines parameters for a Watcher object.

System capability: SystemCapability.HiviewDFX.HiAppEvent

TriggerCondition

Defines callback triggering conditions. Subscription callback is triggered when any condition is met.

System capability: SystemCapability.HiviewDFX.HiAppEvent

AppEventFilter

Defines parameters for an AppEventFilter object.

System capability: SystemCapability.HiviewDFX.HiAppEvent

AppEventPackageHolder

Defines a subscription data holder for processing subscription events.

System capability: SystemCapability.HiviewDFX.HiAppEvent

constructor

constructor(watcherName: string)

Constructor of the Watcher class. When a watcher is added, the system automatically calls this API to create a subscription data holder object for the watcher and returns the holder object to the application.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Example

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

setSize

setSize(size: number): void

Sets the threshold for the data size of the application event package obtained each time.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Error codes

For details about the error codes, see Application Event Logging Error Codes.

Example

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

takeNext

takeNext(): AppEventPackage

Extracts subscription event data based on the configured data size threshold. If all subscription event data has been extracted, null will be returned.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Example

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

AppEventPackage

Defines parameters for an AppEventPackage object.

System capability: SystemCapability.HiviewDFX.HiAppEvent

hiAppEvent.clearData

clearData(): void

Clears local application event logging data.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Example

hiAppEvent.clearData();

EventType

Enumerates event types.

System capability: SystemCapability.HiviewDFX.HiAppEvent

event

Provides constants that define the names of all predefined events.

System capability: SystemCapability.HiviewDFX.HiAppEvent

param

Provides constants that define the names of all predefined event parameters.

System capability: SystemCapability.HiviewDFX.HiAppEvent