diff --git a/en/application-dev/dfx/hiappevent-guidelines.md b/en/application-dev/dfx/hiappevent-guidelines.md index 54199719cd93a523d8f2b0af14c12578997a02a2..48f725e080441281cd2e88820eeacc6032a2dbab 100644 --- a/en/application-dev/dfx/hiappevent-guidelines.md +++ b/en/application-dev/dfx/hiappevent-guidelines.md @@ -2,89 +2,164 @@ ## When to Use -The event logging function helps applications to log various information generated during running. +The event logging function helps applications log various information generated during running. ## Available APIs JS application event logging APIs are provided by the **hiAppEvent** module. -**Table 1** APIs for event logging +The following table provides only a brief description of related APIs. For details, see [HiAppEvent](../reference/apis/js-apis-hiappevent.md). -| API | Return Value | Description | -| ------------------------------------------------------------ | -------------- | ------------------------------------------------------------ | -| write(string eventName, EventType type, object keyValues, AsyncCallback\ callback): void | void | Logs application events in asynchronous mode. This method uses an asynchronous callback to return the result. | -| write(string eventName, EventType type, object keyValues): Promise\ | Promise\ | Logs application events in asynchronous mode. This method uses a promise to return the result. | +**Table 1** APIs for application event logging -When an asynchronous callback is used, the return value can be processed directly in the callback. When a promise is used, the return value can also be processed in the promise in a similar way. For details about the result codes, see [Event Verification Result Codes](#event-verification-result-codes). +| API | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| write(string eventName, EventType type, object keyValues, AsyncCallback\ callback): void | Logs application events in asynchronous mode. This API uses an asynchronous callback to return the result. | +| write(string eventName, EventType type, object keyValues): Promise\ | Logs application events in asynchronous mode. This API uses a promise to return the result. | +| write(AppEventInfo info, AsyncCallback\ callback): void | Logs application events by domain in asynchronous mode. This API uses an asynchronous callback to return the result.| +| write(AppEventInfo info): Promise\ | Logs application events by domain in asynchronous mode. This API uses a promise to return the result.| -**Table 2** APIs for event logging configuration +When an asynchronous callback is used, the return value can be processed directly in the callback. -| API | Return Value | Description | -| ------------------------------ | ------------ | ------------------------------------------------------------ | -| configure(ConfigOption config) | boolean | Sets the configuration options for application event logging.
The value **true** indicates that the operation is successful, and value **false** indicates the opposite. | +If a promise is used, the return value can also be processed in the promise in a similar way. -## Event Verification Result Codes +For details about the result codes, see [Event Verification Result Codes](#event-verification-result-codes). -| Result Code | Cause | Check Rule | Processing Method | -| ----------- | ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -| 0 | None | Event verification is successful. | Event logging is normal. No action is required. | -| -1 | Invalid event name | The event name is not empty and contains a maximum of 48 characters.
The event name consists of only the following characters: digits (0 to 9), letters (a to z), and underscore (\_).
The event name does not start with a digit or underscore (_). | Ignore this event and do not perform logging. | -| -2 | Invalid event parameter type | The event name must be a string.
The event type must be a number.
The key value must be an object. | Ignore this event and do not perform logging. | -| -99 | Application event logging disabled | The application event logging function is disabled. | Ignore this event and do not perform logging. | -| -100 | Unknown error | None | Ignore this event and do not perform logging. | -| 1 | Invalid key name | The key name is not empty and contains a maximum of 16 characters.
The key name consists of only the following characters: digits (0 to 9), letters (a to z), and underscore (\_).
The key name does not start with a digit or underscore (\_).
The key name does not end with an underscore (_). | Ignore the key-value pair and continue to perform logging. | -| 2 | Invalid key type | The key must be a string. | Ignore the key-value pair and continue to perform logging. | -| 3 | Invalid value type | The supported value types vary depending on the programming language:
boolean, number, string, or Array [basic element] | Ignore the key-value pair and continue to perform logging. | -| 4 | Value too long | The value can contain a maximum of 8*1024 characters. | Ignore the key-value pair and continue to perform logging. | -| 5 | Excess key-value pairs | The number of key-value pairs must be less than or equal to 32. | Ignore the excess key-value pairs and continue to perform logging. | -| 6 | Excess elements in a list value | The number of elements in a list value must be less than or equal to 100. | Truncate the list with only the first 100 elements retained, and continue to perform logging. | -| 7 | Invalid list value | A list value can only be a basic element.
The elements in a list value must be of the same type. | Ignore the key-value pair and continue to perform logging. | +**Table 2** APIs for event logging configuration +| API | Description | +| --------------------------------------- | ---------------------------------------------------- | +| configure(ConfigOption config): boolean | Sets the configuration options for application event logging.| -## How to Develop +**Table 3** APIs for watcher management -In this example, an application event is logged after the application startup execution page is loaded. +| API | Description | +| -------------------------------------------------- | -------------------- | +| addWatcher(Watcher watcher): AppEventPackageHolder | Adds an event watcher.| +| removeWatcher(Watcher watcher): void | Removes an event watcher.| -1. Create a JS application project. In the displayed Project window, choose **entry > src > main** > **js** > **default** > **pages > index**, and double-click index.js. Add the code to log the initial application event after page loading. The sample code is as follows: +**Table 4** APIs for clearing logging data - ```js - import hiAppEvent from '@ohos.hiAppEvent' +| API | Description | +| ----------------- | -------------------- | +| clearData(): void | Clears local logging data.| + +### Event Verification Result Codes + +| Result Code| Cause | Verification Rules | Handling Method | +| ------ | ----------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- | +| 0 | N/A | Event verification is successful. | Event logging is normal. No action is required. | +| -1 | Invalid event name | The name is not empty and contains a maximum of 48 characters.
The name consists of only the following characters: digits (0 to 9), letters (a to z), and underscore \(_).
The name does not start with a digit or underscore \(_).| Ignore this event and do not perform logging. | +| -2 | Invalid event parameter type | The event name must be a string.
The event type must be a number.
The event parameter must be an object.| Ignore this event and do not perform logging. | +| -4 | Invalid event domain name | The name is not empty and contains a maximum of 32 characters.
The name consists of only the following characters: digits (0 to 9), letters (a to z), and underscore \(_).
The name does not start with a digit or underscore \(_).| Ignore this event and do not perform logging. | +| -99 | Application event logging disabled | Application event logging is disabled. | Ignore this event and do not perform logging. | +| -100 | Unknown error | None. | Ignore this event and do not perform logging. | +| 1 | Invalid key name | The name is not empty and contains a maximum of 16 characters.
The name consists of only the following characters: digits (0 to 9), letters (a to z), and underscore \(_).
The name does not start with a digit or underscore \(_).
The name does not end with an underscore \(_).| Ignore the key-value pair and continue to perform logging. | +| 2 | Invalid key type | The key must be a string. | Ignore the key-value pair and continue to perform logging. | +| 3 | Invalid value type | The supported value types vary depending on the programming language:
boolean, number, string, or Array [basic element]| Ignore the key-value pair and continue to perform logging. | +| 4 | Invalid length for values of the string type| For a value of the string type, the maximum length is 8*1024 characters. | Truncate the value with the first 8*1024 characters retained, and continue to perform logging.| +| 5 | Excess key-value pairs | The number of key-value pairs must be less than or equal to 32. | Ignore the excess key-value pairs and continue to perform logging. | +| 6 | Invalid number of elements in values of the array type | For a value of the array type, the number of elements must be less than or equal to 100. | Truncate the array with the first 100 elements retained, and continue to perform logging. | +| 7 | Invalid parameters in values of the array type | For a value of the array type, all the parameters must be of the same type, which can only be boolean, number, or string.| Ignore the key-value pair and continue to perform logging. | + +## Development Procedure + +The following uses a one-time event watcher as an example to illustrate the development procedure. + +1. Create an eTS application project. In the displayed **Project** window, choose **entry** > **src** > **main** > **ets** > **pages** > **index.ets**, and double-click **index.ets**. Then, add three buttons to simulate the process of watching for application events. Wherein, button 1 is used to invoke application event logging, button 2 to add an event watcher that automatically triggers a callback, and button 3 to remove the watcher. The complete sample code is as follows: + + ```ts + import hiAppEvent from '@ohos.hiAppEvent'; - export default { - data: { - title: "" - }, - onInit() { - this.title = this.$t('strings.world'); + @Entry + @Component + struct Index { + @State message: string = 'Hello World' - // 1. Callback mode - hiAppEvent.write("start_event", hiAppEvent.EventType.BEHAVIOR, {"int_data":100, "str_data":"strValue"}, (err, value) => { - if (err) { - console.error(`failed to write event because ${err.code}`); - return; + build() { + Row() { + Column() { + Text(this.message) + .fontSize(50) + .fontWeight(FontWeight.Bold) + + Button("1 writeTest").onClick(()=>{ + hiAppEvent.write({ + domain: "test_domain", + name: "test_event", + eventType: hiAppEvent.EventType.FAULT, + params: { + int_data: 100, + str_data: "strValue" } - console.log(`success to write event: ${value}`); - }); + }).then((value) => { + console.log(`HiAppEvent success to write event: ${value}`); + }).catch((err) => { + console.error(`HiAppEvent failed to write event because ${err.code}`); + }); + }) - // 2. Promise mode - hiAppEvent.write("start_event", hiAppEvent.EventType.BEHAVIOR, {"int_data":100, "str_data":"strValue"}) - .then((value) => { - console.log(`success to write event: ${value}`); - }).catch((err) => { - console.error(`failed to write event because ${err.code}`); - }); - - // 3. Set the application event logging switch. - hiAppEvent.configure({ - disable: true - }); + Button("2 addWatcherTest").onClick(()=>{ + hiAppEvent.addWatcher({ + name: "watcher1", + appEventFilters: [{ domain: "test_domain" }], + triggerCondition: { + row: 2, + size: 1000, + timeOut: 2 + }, + onTrigger: function (curRow, curSize, holder) { + if (holder == null) { + console.error("HiAppEvent holder is null"); + return; + } + let eventPkg = null; + while ((eventPkg = holder.takeNext()) != null) { + console.info("HiAppEvent eventPkg.packageId=" + eventPkg.packageId); + console.info("HiAppEvent eventPkg.row=" + eventPkg.row); + console.info("HiAppEvent eventPkg.size=" + eventPkg.size); + for (const eventInfo of eventPkg.data) { + console.info("HiAppEvent eventPkg.data=" + eventInfo); + } + } + } + }); + }) - // 4. Set the maximum size of the event file storage directory. The default value is 10M. - hiAppEvent.configure({ - maxStorage: '100M' - }); + Button("3 removeWatcherTest").onClick(()=>{ + hiAppEvent.removeWatcher({ + name: "watcher1" + }) + }) + } + .width('100%') } + .height('100%') + } } ``` -2. Tap the run button on the application UI to run the project. +2. Touch the run button on the IDE to run the project. + +3. Touch button 1 on the application UI to start application event logging. If the logging is successful, you'll see the following message in the **Log** window: + + ``` + success to write event: 0 + ``` + +4. On the application UI, touch button 2 to add an event watcher, and touch button 1 for multiple times to perform application event logging. If any callback trigger condition (event count, event data size, and timeout duration) is met, the event watcher will invoke a callback and the event package obtained through the callback will be displayed in the **Log** window. + + ``` + HiAppEvent eventPkg.packageId=0 + HiAppEvent eventPkg.row=2 + HiAppEvent eventPkg.size=308 + HiAppEvent eventPkg.data={"domain_":"test_domain","name_":"test_event","type_":1,"time_":1502096107556,"tz_":"+0000","pid_":4204,"tid_":4223,"int_data":100,"str_data":"strValue"} + ``` + +5. On the application UI, touch button 3 to remove the event watcher. Then, touch button 1 for multiple times to perform application event logging. In such a case, there will be no log information about the callback invoked by the event watcher. + +## Samples + +The following sample is provided to help you better understand how to develop the application event logging feature: + +- [`JsDotTest` (JS) (API8)](https://gitee.com/openharmony/applications_app_samples/tree/master/DFX/JsDotTest) diff --git a/en/application-dev/dfx/hiappevent-overview.md b/en/application-dev/dfx/hiappevent-overview.md index 2a5e36f879a922f3d6bf845e700068c2a299b337..088f3624b0c9638dd5137e1460b3cc832c290de9 100644 --- a/en/application-dev/dfx/hiappevent-overview.md +++ b/en/application-dev/dfx/hiappevent-overview.md @@ -2,10 +2,10 @@ HiAppEvent provides event logging APIs for applications to log the fault, statistical, security, and user behavior events reported during running. Based on event information, you will be able to analyze the running status of your application. -The HiAppEvent module of OpenHarmony can be used to develop application event services and provide functions related to application events, including flushing application events to a disk and querying historical application event data. +The HiAppEvent module can be used to develop application event-related functions, including flushing application events to a disk and querying historical application events. ## Basic Concepts -- **Logging** +**Logging** - Logs changes caused by user operations to provide service data for development, product, and O&M analysis. + A function that logs changes caused by user operations to provide service data for development, product, and O&M analysis. \ No newline at end of file diff --git a/en/application-dev/reference/apis/js-apis-hiappevent.md b/en/application-dev/reference/apis/js-apis-hiappevent.md index c684f0ea4f3c4cdd77de4e189b00e15f41a82855..9f1110f241e37530914961c21f688e67d44b05af 100644 --- a/en/application-dev/reference/apis/js-apis-hiappevent.md +++ b/en/application-dev/reference/apis/js-apis-hiappevent.md @@ -2,7 +2,7 @@ This module provides the application event logging functions, such as writing application events to the event file and managing the event logging configuration. -> ![icon-note.gif](public_sys-resources/icon-note.gif) **NOTE**
+> **NOTE** > The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. @@ -12,75 +12,210 @@ This module provides the application event logging functions, such as writing ap import hiAppEvent from '@ohos.hiAppEvent'; ``` +## How to Use -## hiAppEvent.write +Before using application event logging, you need to understand the requirements for related parameters. + +**Event Domain** + +An event domain is a string that contains a maximum of 32 characters, including digits (0 to 9), letters (a to z), and underscores (_). It cannot start with an underscore (_). + +**Event Name** + +An event name is a string that contains a maximum of 48 characters, including digits (0 to 9), letters (a to z), and underscores (_). It cannot start with an underscore (_). + +**Event Type** + +An event type is an enumerated value of [EventType](#eventtype). + +**Event Parameter** + +An event parameter is an object in key-value pair format, where the key is the parameter name and the value is the parameter value. The requirements are as follows: + +- The parameter name is a string that contains a maximum of 16 characters, including digits (0 to 9), letters (a to z), and underscores (_). It cannot start or end with an underscore (_). +- The parameter value is a string, number, boolean, or array. +- When the parameter value is a string, its maximum length is 8*1024 characters. If this limit is exceeded, excess characters will be truncated. +- When 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. + +**Event Callback** + +Event callback can be a callback or promise that carries the return value obtained by invoking the event logging API. You can add the processing of the return value in the event callback as follows: + +- If the return value is **0**, the event verification is successful, and the event will be directly written to the event file. +- If the return value is greater than **0**, invalid parameters are present in the event, and the event will be written to the event file after the invalid parameters are ignored. +- If the return value is smaller than **0**, the event parameter verification fails, and the event will not be written to the event file. + +**Subscription Callback** + +A subscription callback carries the subscription data obtained by invoking the watcher API. The input parameters are defined as follows: + +- **curRow**: number of events. +- **curSize**: event data size, in bytes. +- **holder**: event data holder, which can be used for processing subscription events. + +## hiAppEvent.write(deprecated) write(eventName: string, eventType: EventType, keyValues: object, callback: AsyncCallback<void>): void -Writes event information to the event file of the current day. This API supports JSON parameters and uses an asynchronous callback to return the result. +> **NOTE**
This API is discarded since API version 9. You are advised to use [hiAppEvent.write](#hiappeventwrite9) instead. + +Writes event information to the event file of the current day. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.HiviewDFX.HiAppEvent **Parameters** -| Name | Type | Mandatory| Description | -| --------- | ------------------------- | ---- | ------------------------------------------------------------ | -| eventName | string | Yes | App event name.
You need to customize the event name. It can contain a maximum of 48 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter. | -| eventType | [EventType](#eventtype) | Yes | Application event type. | -| keyValues | object | Yes | Parameter key-value pair. For a variable-length parameter, enter each pair of parameter name and value in sequence. For a JSON parameter, enter the parameter name as the key and parameter value as the value.
- A key must be a string, and a value must be a string, number, boolean, or Array (which can only be a string, number, or boolean).
- The number of event parameters must be less than or equal to 32.
- The parameter name can contain a maximum of 16 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter and cannot end with an underscore (\_).
- A string value can contain a maximum of 8*1024 characters.
- An array value can contain a maximum of 100 elements. Excess elements will be truncated. | -| callback | AsyncCallback<void> | No | Callback used to process the received return value.
-  Value **0** indicates that the event verification is successful, and the event will be written to the event file asynchronously.
-  A value greater than **0** indicates that invalid parameters are present in the event, and the event will be written to the event file asynchronously after the invalid parameters are ignored.
-  A value smaller than **0** indicates that the event verification fails, and the event will not be written to the event file. | +| Name | Type | Mandatory| Description | +| --------- | ------------------------- | ---- | -------------- | +| eventName | string | Yes | Event name. | +| eventType | [EventType](#eventtype) | Yes | Event type. | +| keyValues | object | Yes | Event parameters. | +| callback | AsyncCallback<void> | No | Event callback.| **Example** ```js hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}, (err, value) => { if (err) { - // Event writing exception: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. + // Event writing error: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. console.error(`failed to write event because ${err.code}`); return; } - // Event writing succeeded. + // Event writing success console.log(`success to write event: ${value}`); }); ``` -## hiAppEvent.write +## hiAppEvent.write(deprecated) write(eventName: string, eventType: EventType, keyValues: object): Promise<void> -Writes event information to the event file of the current day. This API supports JSON parameters and uses a promise to return the result. +> **NOTE**
This API is discarded since API version 9. You are advised to use [hiAppEvent.write](#hiappeventwrite9-1) instead. + +Writes event information to the event file of the current day. This API uses a promise to return the result. **System capability**: SystemCapability.HiviewDFX.HiAppEvent **Parameters** -| Name | Type | Mandatory| Description | -| --------- | ----------------------- | ---- | ------------------------------------------------------------ | -| eventName | string | Yes | App event name.
You need to customize the event name. It can contain a maximum of 48 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter. | -| eventType | [EventType](#eventtype) | Yes | Application event type. | -| keyValues | object | Yes | Parameter key-value pair. For a variable-length parameter, enter each pair of parameter name and value in sequence. For a JSON parameter, enter the parameter name as the key and parameter value as the value.
- A key must be a string, and a value must be a string, number, boolean, or Array (which can only be a string, number, or boolean).
- The number of event parameters must be less than or equal to 32.
- The parameter name can contain a maximum of 16 characters, including digits (0 to 9), letters (a to z), and underscores (\_). It must start with a letter and cannot end with an underscore (\_).
- A string value can contain a maximum of 8*1024 characters.
- An array value can contain a maximum of 100 elements. Excess elements will be truncated. | +| Name | Type | Mandatory| Description | +| --------- | ----------------------- | ---- | ---------- | +| eventName | string | Yes | Event name.| +| eventType | [EventType](#eventtype) | Yes | Event type.| +| keyValues | object | Yes | Event parameters.| **Return value** | Type | Description | | ------------------- | ------------------------------------------------------------ | -| Promise<void> | Promise used to process the callback in the then() and catch() methods when event writing succeeded or failed. | +| Promise<void> | Promise used to asynchronously process the callback in the **then()** and **catch()** methods when event writing succeeded or failed.| **Example** ```js hiAppEvent.write("test_event", hiAppEvent.EventType.FAULT, {"int_data":100, "str_data":"strValue"}) .then((value) => { - // Event writing succeeded. + // Event writing success console.log(`success to write event: ${value}`); }).catch((err) => { - // Event writing exception: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. + // Event writing error: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. console.error(`failed to write event because ${err.code}`); }); ``` +## hiAppEvent.write9+ + +write(info: [AppEventInfo](#appeventinfo9), callback: AsyncCallback<void>): void + +Writes events to the event file of the current day through [AppEventInfo](#appeventinfo9) objects. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.HiviewDFX.HiAppEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| -------- | ------------------------------ | ---- | -------------- | +| info | [AppEventInfo](#appeventinfo9) | Yes | Application event object.| +| callback | AsyncCallback<void> | No | Event callback.| + +**Example** + +```js +hiAppEvent.write({ + domain: "test_domain", + name: "test_event", + eventType: hiAppEvent.EventType.FAULT, + params: { + int_data: 100, + str_data: "strValue" + } +}, (err, value) => { + if (err) { + // Event writing error: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. + console.error(`failed to write event because ${err.code}`); + return; + } + + // Event writing success + console.log(`success to write event: ${value}`); +}); +``` + +## hiAppEvent.write9+ + +write(info: [AppEventInfo](#appeventinfo9)): Promise<void> + +Writes events to the event file of the current day through [AppEventInfo](#appeventinfo9) objects. This API uses a promise to return the result. + +**System capability**: SystemCapability.HiviewDFX.HiAppEvent + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------------------------------ | ---- | -------------- | +| info | [AppEventInfo](#appeventinfo9) | Yes | Application event object.| + +**Return value** + +| Type | Description | +| ------------------- | ------------------------------------------------------------ | +| Promise<void> | Promise used to asynchronously process the callback in the **then()** and **catch()** methods when event writing succeeded or failed.| + +**Example** + +```js +hiAppEvent.write({ + domain: "test_domain", + name: "test_event", + eventType: hiAppEvent.EventType.FAULT, + params: { + int_data: 100, + str_data: "strValue" + } +}).then((value) => { + // Event writing success + console.log(`success to write event: ${value}`); +}).catch((err) => { + // Event writing error: Write the event to the event file after the invalid parameters in the event are ignored, or stop writing the event if the event verification fails. + console.error(`failed to write event because ${err.code}`); +}); +``` + +## AppEventInfo9+ + +Defines parameters for an **AppEventInfo** object. + +**System capability**: SystemCapability.HiviewDFX.HiAppEvent + +| Name | Type | Mandatory| Description | +| --------- | ----------------------- | ---- | ---------- | +| domain | string | Yes | Event domain.| +| name | string | Yes | Event name.| +| eventType | [EventType](#eventtype) | Yes | Event type.| +| params | object | Yes | Event parameters.| ## hiAppEvent.configure @@ -94,15 +229,16 @@ Configures the application event logging function, such as setting the event log | Name| Type | Mandatory| Description | | ------ | ----------------------------- | ---- | ------------------------ | -| config | [ConfigOption](#configoption) | Yes | Configuration items for application event logging. | +| config | [ConfigOption](#configoption) | Yes | Configuration items for application event logging.| **Return value** | Type | Description | | ------- | ----------------------------------------------------------- | -| boolean | Returns **true** if the configuration is successful; returns **false** otherwise. | +| boolean | Returns **true** if the configuration is successful; returns **false** otherwise.| **Example** + ```js // Set the application event logging switch. hiAppEvent.configure({ @@ -115,7 +251,6 @@ hiAppEvent.configure({ }); ``` - ## ConfigOption Provides the configuration items for application event logging. @@ -124,8 +259,205 @@ Provides the configuration items for application event logging. | Name | Type | Mandatory| Description | | ---------- | ------- | ---- | ------------------------------------------------------------ | -| disable | boolean | No | Application event logging switch. The value true means to disable the application event logging function, and the value false means the opposite. | -| maxStorage | string | No | Maximum size of the event file storage directory. The default value is **10M**. If the specified size is exceeded, the oldest event logging files in the storage directory will be deleted to free up space. | +| disable | boolean | No | Application event logging switch. The value **true** means to disable the application event logging function, and the value **false** means the opposite.| +| maxStorage | string | No | Maximum size of the event file storage directory. The default value is 10M. If the specified size is exceeded, the oldest event logging files in the directory will be deleted to free up space.| + +## hiAppEvent.addWatcher9+ + +addWatcher(watcher: [Watcher](#watcher9)): [AppEventPackageHolder](#appeventpackageholder9) + +Adds an event watcher. + +**System capability**: SystemCapability.HiviewDFX.HiAppEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | -------------------- | ---- | ---------------- | +| watcher | [Watcher](#watcher9) | Yes | Event watcher.| + +**Return value** + +| Type | Description | +| ------------------------------------------------ | ------------------------------------ | +| [AppEventPackageHolder](#appeventpackageholder9) | Subscription data holder. If the subscription fails, **null** will be returned.| + +**Example** + +```js +// 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: "domain_test1", + 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; + } + while (true) { + let eventPkg = holder.takeNext(); + if (eventPkg == null) { + return; + } + 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 = holder.takeNext(); + if (eventPkg == null) { + return; + } + 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.removeWatcher9+ + +removeWatcher(watcher: [Watcher](#watcher9)): void + +Removes an event watcher. + +**System capability**: SystemCapability.HiviewDFX.HiAppEvent + +**Parameters** + +| Name | Type | Mandatory| Description | +| ------- | -------------------- | ---- | ---------------- | +| watcher | [Watcher](#watcher9) | Yes | Event watcher.| + +**Example** + +```js +// 1. Define a watcher. +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); +``` + +## Watcher9+ + +Defines parameters for a **Watcher** object. + +**System capability**: SystemCapability.HiviewDFX.HiAppEvent + +| Name | Type | Mandatory| Description | +| ---------------- | ------------------------------------------------------------ | ---- | -------------------------------- | +| name | string | Yes | Unique watcher name.| +| triggerCondition | [TriggerCondition](#triggercondition9) | No | Subscription callback trigger condition. | +| appEventFilters | [AppEventFilter](#appeventfilter9)[] | No | Application event filter criteria. | +| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder9)) => void | No | Subscription callback. | + +## TriggerCondition9+ + +Defines parameters for a **TriggerCondition** object. + +**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. | + +## AppEventFilter9+ + +Defines parameters for an **AppEventFilter** object. + +**System capability**: SystemCapability.HiviewDFX.HiAppEvent + +| Name | Type | Mandatory| Description | +| ---------- | ------------------------- | ---- | ------------------------ | +| domain | string | Yes | Event domain. | +| eventTypes | [EventType](#eventtype)[] | No | Event types.| + +## AppEventPackageHolder9+ + +Defines a subscription data holder for processing subscription events. + +**System capability**: SystemCapability.HiviewDFX.HiAppEvent + +### setSize9+ + +setSize(size: number): void + +Sets the data size threshold for fetching an application event package. The default value is **512*1024**, in bytes. + +**Example** + +```js +holder.setSize(1000); +``` + +### takeNext9+ + +takeNext(): [AppEventPackage](#appeventpackage9) + +Extracts subscription event data based on the configured data size threshold. If all subscription event data has been extracted, **null** will be returned. + +**Example** + +```js +let eventPkg = holder.takeNext(); +``` + +## AppEventPackage9+ + +Defines parameters for an **AppEventPackage** object. + +**System capability**: SystemCapability.HiviewDFX.HiAppEvent + +| Name | Type| Description | +| --------- | -------- | ------------------------------ | +| packageId | number | Event package ID, which is named from **0** in ascending order. | +| row | number | Number of events in the event package. | +| size | number | Data size of the event package, in bytes.| +| data | string[] | Event data in the event package. | + +## hiAppEvent.clearData9+ + +clearData(): void + +Clears local logging data. + +**System capability**: SystemCapability.HiviewDFX.HiAppEvent + +**Example** + +```js +hiAppEvent.clearData(); +``` ## EventType @@ -136,10 +468,10 @@ Enumerates event types. | Name | Default Value| Description | | --------- | ------ | -------------- | -| FAULT | 1 | Fault event| -| STATISTIC | 2 | Statistical event| -| SECURITY | 3 | Security event| -| BEHAVIOR | 4 | Behavior event| +| FAULT | 1 | Fault event.| +| STATISTIC | 2 | Statistical event.| +| SECURITY | 3 | Security event.| +| BEHAVIOR | 4 | Behavior event.| ## Event @@ -152,7 +484,7 @@ Provides constants that define the names of all predefined events. | ------------------------- | -------- | ---- | ---- | -------------------- | | USER_LOGIN | string | Yes | No | User login event. | | USER_LOGOUT | string | Yes | No | User logout event. | -| DISTRIBUTED_SERVICE_START | string | Yes | No | Distributed service startup event. | +| DISTRIBUTED_SERVICE_START | string | Yes | No | Distributed service startup event.| ## Param @@ -161,8 +493,8 @@ Provides constants that define the names of all predefined event parameters. **System capability**: SystemCapability.HiviewDFX.HiAppEvent -| Name | Type | Readable | Writable | Description | +| Name | Type| Readable| Writable| Description | | ------------------------------- | -------- | ---- | ---- | ------------------ | | USER_ID | string | Yes | No | Custom user ID. | -| DISTRIBUTED_SERVICE_NAME | string | Yes | No | Distributed service name. | -| DISTRIBUTED_SERVICE_INSTANCE_ID | string | Yes | No | Distributed service instance ID. | \ No newline at end of file +| DISTRIBUTED_SERVICE_NAME | string | Yes | No | Distributed service name. | +| DISTRIBUTED_SERVICE_INSTANCE_ID | string | Yes | No | Distributed service instance ID.| diff --git a/en/device-dev/subsystems/Readme-EN.md b/en/device-dev/subsystems/Readme-EN.md index 73f0a4dd36b7f09fdffd3cc2d51684d09b886b46..e5d78293306a34d3d61f2cd559f5aa84f62c228b 100644 --- a/en/device-dev/subsystems/Readme-EN.md +++ b/en/device-dev/subsystems/Readme-EN.md @@ -72,7 +72,13 @@ - [Development on Device Security Level Management](subsys-security-devicesecuritylevel.md) - Startup - [Startup](subsys-boot-overview.md) - - [init Module](subsys-boot-init.md) + - init Module + - [init Configuration File](subsys-boot-init-cfg.md) + - [Job Management](subsys-boot-init-jobs.md) + - [Service Management](subsys-boot-init-service.md) + - [Parameter Management](subsys-boot-init-sysparam.md) + - [Sandbox Management](subsys-boot-init-sandbox.md) + - [Plug-in Management](subsys-boot-init-plugin.md) - [appspawn Module](subsys-boot-appspawn.md) - [bootstrap Module](subsys-boot-bootstrap.md) - [FAQs](subsys-boot-faqs.md)