@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.addProcessor11+
addProcessor(processor: Processor): number
Adds a data processor for migrating events to the cloud. The implementation of data processors can be preset in the device. You can set attributes of the data processor based on its constraints.
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 to be added. 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. |
Example
import hilog from '@ohos.hilog';
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}`);
}
Processor11+
Defines a data processor for reporting events.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | 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. |
debugMode | boolean | No | 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. |
routeInfo | string | No | 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. |
appId | string | No | 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. |
onStartReport | boolean | No | 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. |
onBackgroundReport | boolean | No | 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. |
periodReport | number | No | 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. |
batchReport | number | No | 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. |
userIds | string[] | No | Name array of user IDs that can be reported by the data processor. name corresponds to the name parameter of the setUserId API. |
userProperties | string[] | No | Name array of user properties that can be reported by the data processor. name corresponds to the name parameter of the setUserProperty API. |
eventConfigs | AppEventReportConfig[] | No | Array of events that can be reported by the data processor. |
AppEventReportConfig11+
Description of events that can be reported by the data processor.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Mandatory | Description |
---|---|---|---|
domain | string | No | Event domain. The value is a string of up to 16 characters, including digits (0 to 9), letters (a to z), and underscores (_). It must start with a lowercase letter and cannot end with an underscore (_). |
name | string | 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. |
isRealTime | boolean | No | Whether to report events in real time. The value true means to report events, and the value false means the opposite. |
hiAppEvent.removeProcessor11+
removeProcessor(id: number): void
Removes a data processor.
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. |
Error codes
ID | Error Message |
---|---|
401 | Parameter error. |
Example
import hilog from '@ohos.hilog';
try {
let processor: hiAppEvent.Processor = {
name: 'analytics_demo'
};
let id: number = hiAppEvent.addProcessor(processor);
hiAppEvent.removeProcessor(id);
} catch (error) {
hilog.error(0x0000, 'hiAppEvent', `failed to removeProcessor event, code=${error.code}`);
}
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
Name | Type | Mandatory | Description |
---|---|---|---|
info | AppEventInfo | Yes | Application event object. |
callback | AsyncCallback<void> | Yes | Callback used to return the result. |
Error codes
For details about the error codes, see Application Event Logging Error Codes.
ID | Error Message |
---|---|
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. |
Example
import { BusinessError } from '@ohos.base';
import hilog from '@ohos.hilog';
let eventParams: Record<string, number | string> = {
"int_data": 100,
"str_data": "strValue",
};
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<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
Name | Type | Mandatory | Description |
---|---|---|---|
info | AppEventInfo | Yes | Application event object. |
Return value
Type | Description |
---|---|
Promise<void> | Promise used to return the result. |
Error codes
For details about the error codes, see Application Event Logging Error Codes.
ID | Error Message |
---|---|
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. |
Example
import { BusinessError } from '@ohos.base';
import hilog from '@ohos.hilog';
let eventParams: Record<string, number | string> = {
"int_data": 100,
"str_data": "strValue",
};
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}`);
});
AppEventInfo
Defines parameters for an AppEventInfo object.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Mandatory | Description |
---|---|---|---|
domain | string | Yes | Event domain. The value is a string of up to 16 characters, including digits (0 to 9), letters (a to z), and underscores (_). It must start with a lowercase letter and cannot end with an underscore (_). |
name | string | 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. |
eventType | EventType | Yes | Event type. |
params | object | Yes | Event parameter object, which consists of a parameter name and a parameter value. The specifications are as follows: - A parameter name is a string that contains a maximum of 16 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 can be a string, number, boolean, or array. If the parameter value is a string, its maximum length is 8*1024 characters. If this limit is exceeded, excess characters will be discarded. If the parameter value is a number, the value must be within the range of Number.MIN_SAFE_INTEGER to Number.MAX_SAFE_INTEGER. Otherwise, uncertain values may be generated. If the parameter value is an array, the elements in the array must be of the same type, which can only be string, number, or boolean. In addition, 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. |
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
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 |
---|---|
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.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Mandatory | Description |
---|---|---|---|
disable | boolean | No | Whether to enable the event logging function. The default value is false. The value true means to disable the event logging function, and the value false means the opposite. |
maxStorage | string | No | Quota for the directory that stores event logging files. The default value is 10M. 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. |
hiAppEvent.setUserId11+
setUserId(name: string, value: string): void
Sets a user ID.
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. |
Example
import hilog from '@ohos.hilog';
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 by setUserId.
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. |
Example
import hilog from '@ohos.hilog';
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 user properties.
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 is a string that contains a maximum of 1024 characters. If the value is null, undefine, or empty, the user property is cleared. |
Error codes
ID | Error Message |
---|---|
401 | Parameter error. |
Example
import hilog from '@ohos.hilog';
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 by setUserProperty.
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. |
Example
import hilog from '@ohos.hilog';
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.addWatcher
addWatcher(watcher: Watcher): AppEventPackageHolder
Adds a watcher to subscribe to application events.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
watcher | Watcher | Yes | Watcher for application events. |
Return value
Type | Description |
---|---|
AppEventPackageHolder | Subscription data holder. If the subscription fails, null will be returned. |
Error codes
For details about the error codes, see Application Event Logging Error Codes.
ID | Error Message |
---|---|
11102001 | Invalid watcher name. |
11102002 | Invalid filtering event domain. |
11102003 | Invalid row value. |
11102004 | Invalid size value. |
11102005 | Invalid timeout value. |
Example
import hilog from '@ohos.hilog';
// 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: (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}`);
}
}
}
});
// 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: 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}`);
}
}
}
// 3. You can have the watcher processed the subscription event in the onReceive function.
hiAppEvent.addWatcher({
name: "watcher3",
appEventFilters: [
{
domain: "test_domain",
eventTypes: [hiAppEvent.EventType.FAULT, hiAppEvent.EventType.BEHAVIOR]
}
],
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 a watcher to unsubscribe from application events.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
watcher | Watcher | Yes | Watcher for application events. |
Error codes
For details about the error codes, see Application Event Logging Error Codes.
ID | Error Message |
---|---|
11102001 | Invalid watcher name. |
Example
// 1. Define a watcher for application events.
let watcher: hiAppEvent.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
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Unique name of a watcher. |
triggerCondition | TriggerCondition | No | Subscription callback triggering condition. This parameter takes effect only when it is passed together with onTrigger. |
appEventFilters | AppEventFilter[] | No | Subscription filtering condition. This parameter is passed only when subscription events need to be filtered. |
onTrigger | (curRow: number, curSize: number, holder: AppEventPackageHolder) => void | No | 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 | 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 callback triggering conditions. A callback is triggered when any specified condition is met.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Mandatory | Description |
---|---|---|---|
row | number | No | Number of events. |
size | number | No | Event data size, in bytes. |
timeOut | number | No | Timeout interval, in unit of 30s. |
AppEventFilter
Defines parameters for an AppEventFilter object.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Mandatory | Description |
---|---|---|---|
domain | string | Yes | Event domain. |
eventTypes | EventType[] | No | Event types. |
names11+ | string[] | No | Names of the events to be subscribed. |
AppEventPackageHolder
Defines a subscription data holder for processing subscription events.
constructor
constructor(watcherName: string)
A constructor used to create a holder object for subscription data. It is associated with a Watcher object based on its name.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
watcherName | string | Yes | Watcher name. |
Example
let holder1: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher1");
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
Name | Type | Mandatory | Description |
---|---|---|---|
size | number | Yes | Data size threshold, in bytes. The default value is 512*1024. |
Error codes
For details about the error codes, see Application Event Logging Error Codes.
ID | Error Message |
---|---|
11104001 | Invalid size value. |
Example
let holder2: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher2");
holder2.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
Return value
Type | Description |
---|---|
AppEventPackage | Event package object. If all subscription event data has been retrieved, null is returned. |
Example
let holder3: hiAppEvent.AppEventPackageHolder = new hiAppEvent.AppEventPackageHolder("watcher3");
let eventPkg = holder3.takeNext();
AppEventPackage
Defines parameters for an AppEventPackage object.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Mandatory | Description |
---|---|---|---|
packageId | number | Yes | Event package ID, which is named from 0 in ascending order. |
row | number | Yes | Number of events in the event package. |
size | number | Yes | Event size of the event package, in bytes. |
data | string[] | Yes | Event data in the event package. |
AppEventGroup11+
Defines the event group returned by a subscription.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Mandatory | Description |
---|---|---|---|
name | string | Yes | Event name. |
appEventInfos | Array<AppEventInfo> | Yes | Event object group. |
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
Name | Value | Description |
---|---|---|
FAULT | 1 | Fault event. |
STATISTIC | 2 | Statistical event. |
SECURITY | 3 | Security event. |
BEHAVIOR | 4 | Behavior event. |
domain11+
Defines the domain name of predefined events.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Description |
---|---|---|
OS | string | System domain. |
event
Defines the names of predefined events.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Description |
---|---|---|
USER_LOGIN | string | User login event. |
USER_LOGOUT | string | User logout event. |
DISTRIBUTED_SERVICE_START | string | Distributed service startup event. |
APP_CRASH11+ | string | Application crash event. |
APP_FREEZE11+ | string | Application freeze event. |
param
Defines the names of predefined event parameters.
System capability: SystemCapability.HiviewDFX.HiAppEvent
Name | Type | Description |
---|---|---|
USER_ID | string | Custom user ID. |
DISTRIBUTED_SERVICE_NAME | string | Distributed service name. |
DISTRIBUTED_SERVICE_INSTANCE_ID | string | Distributed service instance ID. |