harmony 鸿蒙@ohos.hiviewdfx.hiAppEvent (Application Event Logging)

  • 2025-06-12
  • 浏览 (7)

@ohos.hiviewdfx.hiAppEvent (Application Event Logging)

This module provides application logging and event subscription capabilities, including event storage, event subscription, event clearance, and logging configuration. HiAppEvent records the events triggered during application running in AppEventInfo, and classifies the events into system events and application events.

System events are triggered in system services and are predefined in the system. The fields of the event parameter object params of such events are defined by each system event. For details, see overviews of user guides. For example, Crash Event Overview.

Application events are defined by application developers and can be customized using the Write API as required.

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 '@kit.PerformanceAnalysisKit';

hiAppEvent.addWatcher

addWatcher(watcher: Watcher): AppEventPackageHolder

Adds an event watcher. You can use the callback of the event watcher to subscribe to events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
watcher Watcher Yes Event watcher.

Return value

Type Description
AppEventPackageHolder Subscription data holder. If the subscription fails, null is returned.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
11102001 Invalid watcher name.
11102002 Invalid filtering event domain.
11102003 Invalid row value.
11102004 Invalid size value.
11102005 Invalid timeout value.

Example

Based on the type of the event watcher, the following methods are available:

Method 1: If callback parameters are passed to the watcher, you can have subscription events processed in the callback that is automatically triggered.

import { hilog } from '@kit.PerformanceAnalysisKit';

hiAppEvent.addWatcher({
  name: "watcher1",
  // Subscription filters. The application crash event in the system event domain is subscribed.
  appEventFilters: [
    {
      domain: hiAppEvent.domain.OS,
      names: [hiAppEvent.event.APP_CRASH]
    }
  ],
  // Set the condition for triggering the onTrigger callback. The callback is triggered when the total number of events reaches 10, the total event size reaches 1000 bytes, or the event lasts for more than 30s.
  triggerCondition: {
    row: 10,
    size: 1000,
    timeOut: 1
  },
  // Implement the onTrigger callback with triggerCondition. When the callback condition is met, the callback is triggered. After the callback notification is received, use takeNext() to query the subscribed event.
  onTrigger: (curRow: number, curSize: number, holder: hiAppEvent.AppEventPackageHolder) => {
    if (holder == null) {
      hilog.error(0x0000, 'hiAppEvent', "holder is null");
      return;
    }
    hilog.info(0x0000, 'hiAppEvent', `curRow=${curRow}, curSize=${curSize}`);
    let eventPkg: hiAppEvent.AppEventPackage|null = null;
    while ((eventPkg = holder.takeNext()) != null) {
      hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`);
      hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`);
      hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`);
      for (const eventInfo of eventPkg.data) {
        hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`);
      }
    }
  }
});

Method 2: If no callback parameters are passed to the watcher, you can have subscription events processed manually through the subscription data holder.
For the crash event (hiAppEvent.event.APP_CRASH) and freeze event (hiAppEvent.event.APP_FREEZE) generated during abnormal exit, it takes some time for the system to capture debug logs. In typical cases, the capture is completed within 30s, in extreme cases, it takes about 2 minutes.
When the subscription data holder is used to manually process subscription events, the events may not be generated or the log capture is not complete. Therefore, you are advised to call takeNext() to obtain such events again after the process is started.

import { hilog } from '@kit.PerformanceAnalysisKit';

let holder: hiAppEvent.AppEventPackageHolder = hiAppEvent.addWatcher({
  name: "watcher2",
  // Subscription filters. The application crash event in the system event domain is subscribed.
  appEventFilters: [
    {
      domain: hiAppEvent.domain.OS,
      names: [hiAppEvent.event.APP_CRASH]
    }
  ],
});
// Obtain crash events through the subscription data holder.
if (holder != null) {
  let eventPkg: hiAppEvent.AppEventPackage|null = null;
  while ((eventPkg = holder.takeNext()) != null) {
    hilog.info(0x0000, 'hiAppEvent', `eventPkg.packageId=${eventPkg.packageId}`);
    hilog.info(0x0000, 'hiAppEvent', `eventPkg.row=${eventPkg.row}`);
    hilog.info(0x0000, 'hiAppEvent', `eventPkg.size=${eventPkg.size}`);
    for (const eventInfo of eventPkg.data) {
      hilog.info(0x0000, 'hiAppEvent', `eventPkg.data=${eventInfo}`);
    }
  }
}

Method 3: You can have the watcher processed the subscription event in the onReceive function in real time.

import { hilog } from '@kit.PerformanceAnalysisKit';

hiAppEvent.addWatcher({
  name: "watcher3",
  // Subscription filters. The application crash event in the system event domain is subscribed.
  appEventFilters: [
    {
      domain: hiAppEvent.domain.OS,
      names: [hiAppEvent.event.APP_CRASH]
    }
  ],
  // Implement the onReceive callback, which is called in real time after an event is detected.
  onReceive: (domain: string, appEventGroups: Array<hiAppEvent.AppEventGroup>) => {
    hilog.info(0x0000, 'hiAppEvent', `domain=${domain}`);
    for (const eventGroup of appEventGroups) {
      hilog.info(0x0000, 'hiAppEvent', `eventName=${eventGroup.name}`);
      for (const eventInfo of eventGroup.appEventInfos) {
        hilog.info(0x0000, 'hiAppEvent', `event=${JSON.stringify(eventInfo)}`, );
      }
    }
  }
});

hiAppEvent.removeWatcher

removeWatcher(watcher: Watcher): void

Removes an event watcher.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
watcher Watcher Yes Event watcher.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
11102001 Invalid watcher name.

Example

// 1. Define an event watcher.
let watcher: hiAppEvent.Watcher = {
  name: "watcher1",
}

// 2. Add an event watcher to subscribe to events.
hiAppEvent.addWatcher(watcher);

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

hiAppEvent.setEventParam12+

setEventParam(params: Record&lt;string, ParamType&gt;, domain: string, name?: string): Promise&lt;void&gt;

Sets custom event parameters. This API uses a promise to return the result. During the same lifecycle, system events and application events can be associated through event domain and event name. System events only support crash and freeze events.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
params Record&lt;string, ParamType&gt; Yes Custom parameter object. The parameter name and value are defined as follows:
- A parameter name is a string that contains a maximum of 32 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must start with a letter or dollar sign ($) and end with a digit or letter.
- The parameter value is of the ParamType and contains a maximum of 1024 characters.
- The number of parameters must be less than 64.
domain string Yes Event domain. The event domain can be associated with application events and system events (hiAppEvent.domain.OS).
name string No Event name. The default value is an empty string, which indicates all event names in the associated event domain. The event name can be associated with application events and system events. System events can be associated only with crash events (hiAppEvent.event.APP_CRASH) and freeze events (hiAppEvent.event.APP_FREEZE).

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
11101007 The number of parameter keys exceeds the limit.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let params: Record<string, hiAppEvent.ParamType> = {
  "int_data": 100,
  "str_data": "strValue",
};

// Add custom parameters to the application event.
hiAppEvent.setEventParam(params, "test_domain", "test_event").then(() => {
  hilog.info(0x0000, 'hiAppEvent', `success to set event param`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`);
});

hiAppEvent.setEventConfig15+

setEventConfig(name: string, config: Record&lt;string, ParamType&gt;): Promise&lt;void&gt;

Sets the custom threshold triggering condition for an event. This API uses a promise to return the result. In the same lifecycle, you can customize the parameters related to the event threshold triggering condition based on the event name. Currently, only the MAIN_THREAD_JANK event is supported. For details about the parameter configuration, see Main Thread Jank Event Overview.

Atomic service API: This API can be used in atomic services since API version 15.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
name string Yes Event name.
config Record Yes Custom parameter object. The parameter name and value are defined as follows:
- The parameter name contains a maximum of 1024 characters, which is of the string type and cannot be empty.
- The parameter value is of the ParamType and contains a maximum of 1024 characters.

Return value

Type Description
Promise&lt;void&gt; Promise used to return the result.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3.Parameter verification failed.

Example

The following examples describe how to configure the triggering conditions for the MAIN_THREAD_JANK event using three types of log_type.

Set log_type to 0 to sample the stack or trace.

import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let params: Record<string, hiAppEvent.ParamType> = {
  "log_type": "0"
};
hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => {
  hilog.info(0x0000, 'hiAppEvent', `success to set event config`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`);
});

Set log_type to 1 to collect only the call stack.

import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let params: Record<string, hiAppEvent.ParamType> = {
  "log_type": "1",
  "sample_interval": "100",
  "ignore_startup_time": "11",
  "sample_count": "21",
  "report_times_per_app": "3"
};
hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => {
  hilog.info(0x0000, 'hiAppEvent', `success to set event config`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`);
});

Set log_type to 2 to collect only the trace.

import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let params: Record<string, hiAppEvent.ParamType> = {
  "log_type": "2"
};
hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => {
  hilog.info(0x0000, 'hiAppEvent', `success to set event config`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`);
});

Watcher

Defines parameters for a Watcher object. This API is used to configure and manage event watchers to subscribe to and process specified events.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Optional Description
name string No No Unique name of a watcher. The value contains a maximum of 32 characters, including digits (0 to 9), letters (a to z), and underscore (_). It must start with a letter and end with a digit or letter. For example, testName1 and crash_Watcher.
triggerCondition TriggerCondition No Yes Subscription callback triggering condition. This parameter takes effect only when it is passed together with onTrigger. If this parameter is not set, the onTrigger callback is not triggered by default.
appEventFilters AppEventFilter[] No Yes Subscription filtering condition. This parameter is passed only when subscription events need to be filtered. If this parameter is not set, events are not filtered by default.
onTrigger (curRow: number, curSize: number, holder: AppEventPackageHolder) => void No Yes Subscription callback. This parameter takes effect only when it is passed together with triggerCondition. The input arguments are described as follows:
curRow: total number of subscription events when the callback is triggered.
curSize: total size of subscribed events when the callback is triggered, in bytes.
holder: subscription data holder, which can be used to process subscribed events.
onReceive11+ (domain: string, appEventGroups: Array<AppEventGroup>) => void No Yes Real-time subscription callback. Only this callback function is triggered if it is passed together with onTrigger. The input arguments are described as follows:
domain: domain name.
appEventGroups: event group.

TriggerCondition

Defines the triggering condition parameters of the onTrigger callback of a Watcher.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Optional Description
row number No Yes Total number of events that trigger callback. The value is a positive integer. The default value is 0, indicating that no callback is triggered. If this parameter is set to a negative value, the default value is used.
size number No Yes Total size of events that trigger callback. The value is a positive integer, in bytes. The default value is 0, indicating that no callback is triggered. If this parameter is set to a negative value, the default value is used.
timeOut number No Yes Timeout interval for triggering callback. The value is a positive integer, in unit of 30s. The default value is 0, indicating that no callback is triggered. If this parameter is set to a negative value, the default value is used.

AppEventFilter

Defines parameters of subscription filtering conditions of a Watcher. This API is used to set event filtering conditions in the event watcher to ensure that only the events that meet the filtering conditions are subscribed to.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Optional Description
domain string No No Event domain, which can be the system event domain (hiAppEvent.domain.OS) or the event domain of the custom event information (AppEventInfo) passed through the Write API.
eventTypes EventType[] No Yes Event types. If this parameter is not set, events are not filtered by default.
names11+ string[] No Yes Names of the events to be subscribed. If this parameter is not set, events are not filtered by default.

AppEventPackageHolder

Defines a subscription data holder for processing event information.

constructor

constructor(watcherName: string)

Constructs an AppEventPackageHolder instance. You can call addWatcher to add an event watcher, and then associate the AppEventPackageHolder instance with the watcher added in the application based on the watcher name.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
watcherName string Yes Name of the event watcher added through addWatcher. If no watcher is added, no data is displayed by default.

Example

// Add the Watcher1 to subscribe to system events.
hiAppEvent.addWatcher({
  name: "Watcher1",
  appEventFilters: [
    {
      domain: hiAppEvent.domain.OS,
    }
  ],
  });

// Create an AppEventPackageHolder instance. holder1 holds the event data subscribed by Watcher1 added through addWatcher.
let holder1: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("Watcher1");

setSize

setSize(size: number): void

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

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
size number Yes Data size threshold, in bytes. The value range is [0, $2^{31}$-1]. If the value is out of the range, an exception is thrown.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
11104001 Invalid size value.

Example

let holder2: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher2");
holder2.setSize(1000);

setRow12+

setRow(size: number): void

Sets the number of data records of the event package obtained each time. When setRow() and setSize() are called at the same time, only setRow() takes effect.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
size number Yes Number of events. The value range is (0, $2^{31}$-1]. If the value is out of the range, an exception is thrown.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
11104001 Invalid size value.

Example

let holder3: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher3");
holder3.setRow(1000);

takeNext

takeNext(): AppEventPackage

Obtains the subscription event.

The system obtains the subscription event data based on the data size threshold specified by setSize or the number of data records specified by setRow. By default, one subscription event data record is obtained. When all subscription event data is obtained, null is returned.

When setRow and setSize are called at the same time, only setRow takes effect.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Return value

Type Description
AppEventPackage Event package object. If all subscription event data has been retrieved, null is returned.

Example

let holder4: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher4");
let eventPkg: hiAppEvent.AppEventPackage|null = holder4.takeNext();

AppEventInfo

Defines parameters of the event information.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Optional Description
domain string No No Event domain. The value is a string of up to 32 characters, including digits (0 to 9), letters (a to z), and underscores (_). It must start with a letter and cannot end with an underscore (_).
name string No No Event name. The value is string that contains a maximum of 48 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must start with a letter or dollar sign ($) and end with a digit or letter.
eventType EventType No No Event type.
params object No No Event parameter object, which consists of a parameter name and a parameter value. In system events, the fields contained in params are defined by system. For details about the fields, you can see the overviews of system events, for example, Crash Event Overview. For application events, you need to define the parameters of the Write API. The specifications are as follows:
- A parameter name is a string that contains a maximum of 32 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must start with a letter or dollar sign ($) and end with a digit or letter. For example, testName and \$123_name.
- The parameter value can be a string, number, boolean, or array. The string type parameter can contain a maximum of 8 x 1024 characters. If the length exceeds the limit, the parameter and its name will be discarded. The value of the number type parameter must be within the range of Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER. If the value exceeds the range, an uncertain value may be generated. The element type in the array type parameter can only be string, number, or boolean. The number of elements must be less than 100. If this limit is exceeded, excess elements will be discarded.
- The maximum number of parameters is 32. If this limit is exceeded, excess parameters will be discarded.

AppEventPackage

Defines parameters of an AppEventPackage object. This API is used to obtain detail information about an event package, which is obtained using the takeNext API.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Optional Description
packageId number Yes No Event package ID, which is named from 0 in ascending order.
Atomic service API: This API can be used in atomic services since API version 11.
row number Yes No Number of events in the event package.
Atomic service API: This API can be used in atomic services since API version 11.
size number Yes No Event size of the event package, in bytes.
Atomic service API: This API can be used in atomic services since API version 11.
data string[] Yes No Event data in the event package.
Atomic service API: This API can be used in atomic services since API version 11.
appEventInfos12+ Array<AppEventInfo> Yes No Event object group.
Atomic service API: This API can be used in atomic services since API version 12.

AppEventGroup11+

Defines parameters of the event group returned by a subscription. This API can be used to obtain detail information about an event group, which is often used in the onReceive callback of Watcher.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Optional Description
name string Yes No Event name.
appEventInfos Array<AppEventInfo> Yes No Event object group.

hiAppEvent.write

write(info: AppEventInfo, callback: AsyncCallback&lt;void&gt;): void

Writes events of the AppEventInfo type. This API uses an asynchronous callback to return the result. The event object written by calling this API is a custom object. To avoid conflicts with system events, you are not advised to write it to system events (system event name constants defined in Event). The events written by this API can be subscribed to through (addWatcher).

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
info AppEventInfo Yes Application event object. You are advised to avoid the conflict between the custom event name and the system event name constant defined in Event.
callback AsyncCallback&lt;void&gt; Yes Callback used to return the result.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
11100001 Function 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.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let eventParams: Record<string, number|string> = {
  "int_data": 100,
  "str_data": "strValue",
};

// Application event logging. This API uses an asynchronous callback to return the result.
hiAppEvent.write({
  domain: "test_domain",
  name: "test_event",
  eventType: hiAppEvent.EventType.FAULT,
  params: eventParams,
}, (err: BusinessError) => {
  if (err) {
    hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`);
    return;
  }
  hilog.info(0x0000, 'hiAppEvent', `success to write event`);
});

hiAppEvent.write

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

Writes events of the AppEventInfo type. This API uses a promise to return the result. The event object written by calling this API is a custom object. To avoid conflicts with system events, you are not advised to write it to system events (system event name constants defined in Event). The events written by this API can be subscribed to through (addWatcher).

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
info AppEventInfo Yes Application event object. You are advised to avoid the conflict between the custom event name and the system event name constant defined in Event.

Return value

Type Description
Promise&lt;void&gt; Promise that returns no value.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
11100001 Function 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.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let eventParams: Record<string, number|string> = {
  "int_data": 100,
  "str_data": "strValue",
};

// Application event logging. This API uses a promise to return the result.
hiAppEvent.write({
  domain: "test_domain",
  name: "test_event",
  eventType: hiAppEvent.EventType.FAULT,
  params: eventParams,
}).then(() => {
  hilog.info(0x0000, 'hiAppEvent', `success to write event`);
}).catch((err: BusinessError) => {
  hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`);
});

hiAppEvent.addProcessor11+

addProcessor(processor: Processor): number

Adds a data processor to migrate event data to the cloud. You can preset the implementation of the processor on the device and set its properties based on its constraints.

The configuration information of Processor must be provided by the data processor. Yet, as no data processor is preset in the device for interaction for the moment, migrating events to the cloud is unavailable.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
processor Processor Yes Data processor.

Return value

Type Description
number ID of the data processor of the reported event, which uniquely identifies the data processor and can be used to remove the data processor. If the operation fails, -1 is returned. If the operation is successful, a value greater than 0 is returned.

Error codes

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';

try {
    let processor: hiAppEvent.Processor = {
      name: 'analytics_demo'
    };
    let id: number = hiAppEvent.addProcessor(processor);
    hilog.info(0x0000, 'hiAppEvent', `addProcessor event was successful, id=${id}`);
} catch (error) {
    hilog.error(0x0000, 'hiAppEvent', `failed to addProcessor event, code=${error.code}`);
}

hiAppEvent.removeProcessor11+

removeProcessor(id: number): void

Removes the data processor of a reported event.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
id number Yes ID of a data processor. The value must be greater than 0. The value is obtained by calling addProcessor.

Error codes

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';

try {
    let processor: hiAppEvent.Processor = {
      name: 'analytics_demo'
    };
    let id: number = hiAppEvent.addProcessor(processor);
    // Remove a specified data processor based on the ID returned after the data processor is added.
    hiAppEvent.removeProcessor(id);
} catch (error) {
    hilog.error(0x0000, 'hiAppEvent', `failed to removeProcessor event, code=${error.code}`);
}

hiAppEvent.setUserId11+

setUserId(name: string, value: string): void

Sets a user ID, which is used for association when a Processor is configured.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
name string Yes Key of a user ID. The value is string that contains a maximum of 256 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must not start with a digit.
value string Yes Value of a user ID. It can contain a maximum of 256 characters. If the value is null or left empty, the user ID is cleared.

Error codes

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';

try {
  hiAppEvent.setUserId('key', 'value');
} catch (error) {
  hilog.error(0x0000, 'hiAppEvent', `failed to setUserId event, code=${error.code}`);
}

hiAppEvent.getUserId11+

getUserId(name: string): string

Obtains the value set through setUserId.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
name string Yes Key of a user ID. The value is string that contains a maximum of 256 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must not start with a digit.

Return value

Type Description
string Value of a user ID. If no user ID is found, an empty string is returned.

Error codes

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';

hiAppEvent.setUserId('key', 'value');
try {
  let value: string = hiAppEvent.getUserId('key');
  hilog.info(0x0000, 'hiAppEvent', `getUserId event was successful, userId=${value}`);
} catch (error) {
  hilog.error(0x0000, 'hiAppEvent', `failed to getUserId event, code=${error.code}`);
}

hiAppEvent.setUserProperty11+

setUserProperty(name: string, value: string): void

Sets a user property, which is used for association when a Processor is configured.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
name string Yes Key of a user property. The value is string that contains a maximum of 256 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must not start with a digit.
value string Yes Value of a user property. It can contain a maximum of 1024 characters. If the value is null or left empty, the user property is cleared.

Error codes

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';

try {
  hiAppEvent.setUserProperty('key', 'value');
} catch (error) {
  hilog.error(0x0000, 'hiAppEvent', `failed to setUserProperty event, code=${error.code}`);
}

hiAppEvent.getUserProperty11+

getUserProperty(name: string): string

Obtains the value set through setUserProperty.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
name string Yes Key of a user property. The value is string that contains a maximum of 256 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must not start with a digit.

Return value

Type Description
string Value of a user property. If no user ID is found, an empty string is returned.

Error codes

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.

Example

import { hilog } from '@kit.PerformanceAnalysisKit';

hiAppEvent.setUserProperty('key', 'value');
try {
  let value: string = hiAppEvent.getUserProperty('key');
  hilog.info(0x0000, 'hiAppEvent', `getUserProperty event was successful, userProperty=${value}`);
} catch (error) {
  hilog.error(0x0000, 'hiAppEvent', `failed to getUserProperty event, code=${error.code}`);
}

hiAppEvent.clearData

clearData(): void

Clears local logging data of the application.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Example

hiAppEvent.clearData();

hiAppEvent.configure

configure(config: ConfigOption): void

Configures the application event logging function, such as setting the logging switch and directory storage quota.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Parameters

Name Type Mandatory Description
config ConfigOption Yes Configuration items for application event logging.

Error codes

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

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
11103001 Invalid max storage quota value.

Example

// Disable the event logging function.
let config1: hiAppEvent.ConfigOption = {
  disable: true,
};
hiAppEvent.configure(config1);

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

ConfigOption

Provides configuration options for application event logging.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Optional Description
disable boolean No Yes Whether to enable the event logging function. The default value is false. If this parameter is set to true, the logging function is disabled. Otherwise, the logging function is enabled.
maxStorage string No Yes Quota for the directory that stores event logging files. The default value is 10M. It is recommended that the quota be less than or equal to 10 MB. Otherwise, the API efficiency may be affected.
If the directory size exceeds the specified quota when application event logging is performed, event logging files in the directory will be cleared one by one based on the generation time to ensure that directory size does not exceed the quota.
The quota value must meet the following requirements:
- The quota value consists of only digits and a unit (which can be one of [b|k|kb|m|mb|g|gb|t|tb], which are case insensitive.)
- The quota value must start with a digit. You can determine whether to pass the unit. If the unit is left empty, b (that is, byte) is used by default.

Processor11+

Defines a data processor for reporting and managing events. You can customize processor configurations as required.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Optional Description
name string No No Name of a data processor. The value is string that contains a maximum of 256 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must not start with a digit.
Atomic service API: This API can be used in atomic services since API version 11.
debugMode boolean No Yes Whether to enable the debug mode. The default value is false. The value true means to enable the debugging mode, and the value false means the opposite.
Atomic service API: This API can be used in atomic services since API version 11.
routeInfo string No Yes Server location information. It is left empty by default. The length of the input string cannot exceed 8 KB. If the length exceeds 8 KB, the default value is used.
Atomic service API: This API can be used in atomic services since API version 11.
appId string No Yes Application ID. It is left empty by default. The length of the input string cannot exceed 8 KB. If the length exceeds 8 KB, the default value is used.
Atomic service API: This API can be used in atomic services since API version 11.
onStartReport boolean No Yes Whether to report an event when the data processor starts. The default value is false. The value true means to report events, and the value false means the opposite.
Atomic service API: This API can be used in atomic services since API version 11.
onBackgroundReport boolean No Yes Whether to report an event when an application switches to the background. The default value is false. The value true means to report events, and the value false means the opposite.
Atomic service API: This API can be used in atomic services since API version 11.
periodReport number No Yes Interval for event reporting, in seconds. The input value must be greater than or equal to 0. If the input value is less than 0, the default value 0 is used and periodic reporting is not performed.
Atomic service API: This API can be used in atomic services since API version 11.
batchReport number No Yes Event reporting threshold. When the number of events reaches the threshold, an event is reported. The value must be greater than 0 and less than 1000. If the value is not within the range, the default value 0 is used and no events are reported.
Atomic service API: This API can be used in atomic services since API version 11.
userIds string[] No Yes Name array of user IDs that can be reported by the data processor. name corresponds to the name parameter of the setUserId API. The default value is an empty array.
Atomic service API: This API can be used in atomic services since API version 11.
userProperties string[] No Yes Name array of user properties that can be reported by the data processor. name corresponds to the name parameter of the setUserProperty API. The default value is an empty array.
Atomic service API: This API can be used in atomic services since API version 11.
eventConfigs AppEventReportConfig[] No Yes Event description configuration array that can be reported by the data processor. The default value is an empty array.
Atomic service API: This API can be used in atomic services since API version 11.
configId12+ number No Yes Configuration ID for data processor. The input value must be greater than or equal to 0. If the input value is less than 0, the default value 0 is used. If the input value is greater than 0, the value uniquely identifies a data processor with its name.
Atomic service API: This API can be used in atomic services since API version 12.
customConfigs12+ Record<string, string> No Yes Custom extended parameters. If the input parameter name and value do not meet the specifications, extended parameters are not configured by default. The specifications are as follows:
- A parameter name is a string that contains a maximum of 32 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must start with a letter or dollar sign ($) and end with a digit or letter.
- A parameter value is a string contains a maximum of 1024 characters.
- The number of parameters must be less than 32.
Atomic service API: This API can be used in atomic services since API version 12.

AppEventReportConfig11+

Event description configuration that can be reported by the data processor.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Optional Description
domain string No Yes Event domain. The value is a string that contains a maximum of 32 characters, including digits (0 to 9), letters (a to z), and underscore (_). It must start with a letter and cannot end with an underscore (_). The default value is an empty string.
name string No Yes Event name. The value is string that contains a maximum of 48 characters, including digits (0 to 9), letters (a to z), underscore (_), and dollar sign ($). It must start with a letter or dollar sign ($) and end with a digit or letter. The default value is an empty string.
isRealTime boolean No Yes Whether to report events in real time. The value true indicates that events are reported in real time, and the value false indicates the opposite. The default value is false.

ParamType12+

type ParamType = number|string|boolean|Array&lt;string&gt;

Type of a custom event parameter value.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Type Description
number Number.
string String.
boolean The value is true or false.
Array&lt;string&gt; The value is an array of strings.

EventType

Enumerates event types.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Value Description
FAULT 1 Fault event.
STATISTIC 2 Statistical event.
SECURITY 3 Security event.
BEHAVIOR 4 Behavior event.

hiappevent.domain11+

Provides domain name constants.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Description
OS string Yes System domain.

hiappevent.event

Provides event name constants, including system event name constants and application event name constants. The application event name constants are optional custom event names reserved when you call Write for application event logging.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Description
USER_LOGIN string Yes User login event. This is a reserved application event name constant.
Atomic service API: This API can be used in atomic services since API version 11.
USER_LOGOUT string Yes User logout event. This is a reserved application event name constant.
Atomic service API: This API can be used in atomic services since API version 11.
DISTRIBUTED_SERVICE_START string Yes Distributed service startup event. This is a reserved application event name constant.
Atomic service API: This API can be used in atomic services since API version 11.
APP_CRASH11+ string Yes Application crash event. This is a system event name constant.
Atomic service API: This API can be used in atomic services since API version 11.
APP_FREEZE11+ string Yes Application freeze event. This is a system event name constant.
Atomic service API: This API can be used in atomic services since API version 11.
APP_LAUNCH12+ string Yes Event indicating the application launch duration. This is a system event name constant.
Atomic service API: This API can be used in atomic services since API version 12.
SCROLL_JANK12+ string Yes Event indicating frame loss during swiping. This is a system event name constant.
Atomic service API: This API can be used in atomic services since API version 12.
CPU_USAGE_HIGH12+ string Yes Event indicating a high CPU usage. This is a system event name constant.
Atomic service API: This API can be used in atomic services since API version 12.
BATTERY_USAGE12+ string Yes Event indicating battery usage statistics. This is a system event name constant.
Atomic service API: This API can be used in atomic services since API version 12.
RESOURCE_OVERLIMIT12+ string Yes Event indicating an application resource leakage. This is a system event name constant.
Atomic service API: This API can be used in atomic services since API version 12.
ADDRESS_SANITIZER12+ string Yes Address sanitizer event. This is a system event name constant.
Atomic service API: This API can be used in atomic services since API version 12.
MAIN_THREAD_JANK12+ string Yes Main thread jank event. This is a system event name constant.
Atomic service API: This API can be used in atomic services since API version 12.

hiappevent.param

Provides parameter name constants.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.HiviewDFX.HiAppEvent

Name Type Read Only Description
USER_ID string Yes Custom user ID.
DISTRIBUTED_SERVICE_NAME string Yes Distributed service name.
DISTRIBUTED_SERVICE_INSTANCE_ID string Yes Distributed service instance ID.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Performance Analysis Kit

harmony 鸿蒙Performance Analysis Kit

harmony 鸿蒙HiAppEvent

harmony 鸿蒙HiAppEvent_AppEventGroup

harmony 鸿蒙HiAppEvent_AppEventInfo

harmony 鸿蒙HiCollie

harmony 鸿蒙HiCollie_DetectionParam

harmony 鸿蒙HiCollie_SetTimerParam

harmony 鸿蒙HiDebug

harmony 鸿蒙HiDebug_MemoryLimit

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