@@ -8,7 +8,7 @@ The event logging function helps applications log various information generated
JS application event logging APIs are provided by the **hiAppEvent** module.
The following table provides only a brief description of related APIs. For details, see [HiAppEvent](../reference/apis/js-apis-hiappevent.md).
The following table provides only a brief description of related APIs. For details, see [HiAppEvent](../reference/apis/js-apis-hiviewdfx-hiappevent.md).
**Table 1** APIs for application event logging
...
...
@@ -17,17 +17,11 @@ The following table provides only a brief description of related APIs. For detai
| write(AppEventInfo info, AsyncCallback\<void> callback): void | Logs application events in asynchronous mode. This API uses an asynchronous callback to return the result.|
| write(AppEventInfo info): Promise\<void> | Logs application events in asynchronous mode. This API uses a promise to return the result. |
When an asynchronous callback is used, the return value can be processed directly in the callback.
If 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).
| 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.<br>The name consists of only the following characters: digits (0 to 9), letters (a to z), and underscore \(_).<br>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.<br>The event type must be a number.<br>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.<br>The name consists of only the following characters: digits (0 to 9), letters (a to z), and underscore \(_).<br>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.<br>The name consists of only the following characters: digits (0 to 9), letters (a to z), and underscore \(_).<br>The name does not start with a digit or underscore \(_).<br>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:<br>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
## How to Develop
The following uses a one-time event watcher as an example to illustrate the development procedure.
1. Create an ArkTS 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:
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
importhiAppEventfrom'@ohos.hiAppEvent';
importhiAppEventfrom'@ohos.hiviewdfx.hiAppEvent';
@Entry
@Component
...
...
@@ -91,10 +67,10 @@ The following uses a one-time event watcher as an example to illustrate the deve
int_data:100,
str_data:"strValue"
}
}).then((value)=>{
console.log(`HiAppEvent success to write event: ${value}`);
}).then(()=>{
console.log(`HiAppEvent success to write event`);
}).catch((err)=>{
console.error(`HiAppEvent failed to write event because ${err.code}`);
This module provides the application event logging functions, such as writing application events to the event file and managing the event logging configuration.
> **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.
> - The APIs provided by this module are deprecated since API version 9. You are advised to use [`@ohos.hiviewdfx.hiAppEvent`](js-apis-hiviewdfx-hiappevent.md) instead.
> - 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.
## Modules to Import
...
...
@@ -17,13 +17,9 @@ import hiAppEvent from '@ohos.hiAppEvent';
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 (\_).
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 must start with a lowercase letter and cannot end with an underscore (_).
**Event Type**
...
...
@@ -33,7 +29,7 @@ An event type is an enumerated value of [EventType](#eventtype).
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 (\_).
-A parameter name is a string that contains a maximum of 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 (\_).
- 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.
...
...
@@ -47,20 +43,10 @@ Event callback can be a callback or promise that carries the return value obtain
- 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.
Writes events to the event file of the current day through [AppEventInfo](#appeventinfo9) objects. This API uses an asynchronous callback to return the result.
| 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}`);
| 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}`);
});
```
## AppEventInfo<sup>9+</sup>
Defines parameters for an **AppEventInfo** object.
| 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 <strong>10M</strong>. If the specified size is exceeded, the oldest event logging files in the directory will be deleted to free up space.|
Extracts subscription event data based on the configured data size threshold. If all subscription event data has been extracted, **null** will be returned.
> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
You can run the hidebug command to obtain the memory usage of an application, including the static heap memory (native heap) and proportional set size (PSS) occupied by the application process. You can also export VM memory slices and collect VM CPU profiling data.
This module provides APIs for you to obtain the memory usage of an application, including the static heap memory (native heap) and proportional set size (PSS) occupied by the application process. You can also export VM memory slices and collect VM CPU profiling data.
## Modules to Import
...
...
@@ -17,7 +16,7 @@ import hidebug from '@ohos.hidebug';
getNativeHeapSize(): bigint
Obtains the total size of the heap memory of this application.
Obtains the total heap memory size of this application.
This API is defined but not implemented in OpenHarmony 3.1 Release.
...
...
@@ -27,7 +26,7 @@ This API is defined but not implemented in OpenHarmony 3.1 Release.
| Type | Description |
| ------ | --------------------------- |
| bigint | Total size of the heap memory of this application, in kB.|
| bigint | Total heap memory size of the application, in KB.|
**Example**
...
...
@@ -40,17 +39,17 @@ This API is defined but not implemented in OpenHarmony 3.1 Release.
getNativeHeapAllocatedSize(): bigint
Obtains the size of the allocated heap memory of this application.
Obtains the allocated heap memory size of this application.
This API is defined but not implemented in OpenHarmony 3.1 Release.
@@ -165,11 +162,13 @@ For example, if the CPU usage is **50%**, **0.5** is returned.
letcpuUsage=hidebug.getCpuUsage();
```
## hidebug.startProfiling
## hidebug.startProfiling<sup>(deprecated)</sup>
startProfiling(filename : string) : void
Starts the profiling method. `startProfiling()` and `stopProfiling()` are called in pairs. `startProfiling()` always occurs before `stopProfiling()`; that is, calling the functions in the following sequences is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`.
> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [hidebug.startJsCpuProfiling](#hidebugstartjscpuprofiling9) instead.
Starts the profiling method. `startProfiling()` and `stopProfiling()` are called in pairs. `startProfiling()` always occurs before `stopProfiling()`; that is, calling the functions in the sequence similar to the following is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`.
Stops the profiling method. `startProfiling()` and `stopProfiling()` are called in pairs. `startProfiling()` always occurs before `stopProfiling()`; that is, calling the functions in the following sequences is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`.
> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [hidebug.stopJsCpuProfiling](#hidebugstopjscpuprofiling9) instead.
Stops the profiling method. `startProfiling()` and `stopProfiling()` are called in pairs. `startProfiling()` always occurs before `stopProfiling()`; that is, calling the functions in the sequence similar to the following is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`.
| filename | string | Yes | User-defined heap file name. The `filename.heapsnapshot` file is generated in the `files` directory of the application based on the specified `filename`.|
Starts the profiling method. `startJsCpuProfiling()` and `stopJsCpuProfiling()` are called in pairs. `startJsCpuProfiling()` always occurs before `stopJsCpuProfiling()`; that is, calling the functions in the sequence similar to the following is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`.
| filename | string | Yes | User-defined profile name. The `filename.json` file is generated in the `files` directory of the application based on the specified `filename`.|
**Example**
```js
importhidebugfrom'@ohos.hidebug'
try{
hidebug.startJsCpuProfiling("cpu_profiling");
...
hidebug.stopJsCpuProfiling();
}catch(error){
console.info(error.code)
console.info(error.message)
}
```
## hidebug.stopJsCpuProfiling<sup>9+</sup>
stopJsCpuProfiling() : void
Stops the profiling method. `startJsCpuProfiling()` and `stopJsCpuProfiling()` are called in pairs. `startJsCpuProfiling()` always occurs before `stopJsCpuProfiling()`; that is, calling the functions in the sequence similar to the following is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`.
| filename | string | Yes | User-defined profile name. The `filename.json` file is generated in the `files` directory of the application based on the specified `filename`.|
| filename | string | Yes | User-defined heap file name. The `filename.heapsnapshot` file is generated in the `files` directory of the application based on the specified `filename`.|
Provides system event logging APIs for system HAP applications.
本模块提供了系统事件打点能力，包括系统事件的埋点、落盘系统事件的订阅及已落盘的系统事件的查询能力。
> **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.
> - The APIs of this module are system APIs.
> **说明：**
> - 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> - 本模块的接口为系统接口。
## Modules to Import
## 导入模块
```js
importhiSysEventfrom'@ohos.hiSysEvent';
...
...
@@ -15,47 +15,62 @@ import hiSysEvent from '@ohos.hiSysEvent';
| info | [SysEventInfo](#syseventinfo) | Yes| System event information.|
| callback | AsyncCallback<void> | Yes| Callback used to process the received return value.<br>- Value **0**: The event verification is successful, and the event will be written to the event file asynchronously. <br>- A value greater than **0**: Invalid parameters are present in the event, and the event will be written to the event file asynchronously after the invalid parameters are ignored.<br>- A value smaller than **0**: The event parameter verification fails, and the event will not be written to the event file.|
| info | [SysEventInfo](#syseventinfo) | 是 | 系统事件。 |
| Promise<void> | Promise used to return the result. Depending on whether event writing is successful, you can use the **then()** or **catch()** method to process the callback.|
This 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.
Writes events to the event file of the current day through [AppEventInfo](#appeventinfo) objects. This API uses an asynchronous callback to return the result.
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.
| 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 | Maximum size of the directory that stores event logging files. The default value is **10M**.<br>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.|
| name | string | Yes | Unique name of the watcher. |
| triggerCondition | [TriggerCondition](#triggercondition) | No | Subscription callback triggering condition. This parameter takes effect only when it is passed together with the callback. |
| appEventFilters | [AppEventFilter](#appeventfilter)[] | No | Subscription filtering condition. This parameter is passed only when subscription events need to be filtered. |
| onTrigger | (curRow: number, curSize: number, holder: [AppEventPackageHolder](#appeventpackageholder)) => void | No | Subscription callback, which takes effect only when it is passed together with the callback triggering condition. The input arguments are described as follows:<br>**curRow**: total number of subscription events when the callback is triggered.<br>**curSize**: total size of subscribed events when the callback is triggered, in bytes.<br>**holder**: subscription data holder, which can be used to process subscribed events.|
## TriggerCondition
Defines callback triggering conditions. Subscription callback is triggered when any condition is met.
Constructor of the **Watcher** class. When a watcher is added, the system automatically calls this API to create a subscription data holder object for the watcher and returns the holder object to the application.
| 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](../errorcodes/errorcode-hiappevent.md).
| ID| Error Message |
| -------- | ------------------- |
| 11104001 | Invalid size value. |
**Example**
```js
letholder=hiAppEvent.addWatcher({
name:"watcher",
});
holder.setSize(1000);
```
### takeNext
takeNext(): [AppEventPackage](#appeventpackage)
Extracts subscription event data based on the configured data size threshold. If all subscription event data has been extracted, **null** will be returned.
This error code is reported if the **write** API is called to perform application event logging but the system ignores related events because the logging function is disabled.
**Possible Causes**
The application event logging function is disabled.
**Solution**
Invoke the **configure** API to enable the application event logging function.
```js
hiAppEvent.configure({
disable:false
});
```
## 11101001 Invalid Event Domain Name
**Error Message**
Invalid event domain.
**Description**
This error code is reported if the **write** API is called to perform application event logging but the system ignores related events because the input event domain name is invalid.
**Possible Causes**
The specified event domain name does not comply with the following rules:
- The event domain name contains only digits, lowercase letters, and underscores (\_).
- The event domain name starts with a lowercase letter and does not end with an underscore (\_).
- The event domain name is not empty and contains a maximum of 32 characters.
**Solution**
Specify a valid event domain name.
## 11101002 Invalid Event Name
**Error Message**
Invalid event name.
**Description**
This error code is reported if the **write** API is called to perform application event logging but the system ignores related events because the input event name is invalid.
**Possible Causes**
The specified event name does not comply with the following rules:
- The event name contains only digits, lowercase letters, and underscores (\_).
- The event name starts with a lowercase letter and does not end with an underscore (\_).
- The event name is not empty and contains a maximum of 48 characters.
**Solution**
Specify a valid event name.
## 11101003 Invalid Number of Event Parameters
**Error Message**
Invalid number of event parameters.
**Description**
This error code is reported if the **write** API is called to perform application event logging but the system discards extra event parameters because the number of input event parameters exceeds the limit.
**Possible Causes**
The number of input event parameters exceeds 32.
**Solution**
Specify a valid number of event parameters.
## 11101004 Invalid Event Parameter String Length
**Error Message**
Invalid string length of the event parameter.
**Description**
This error code is reported if the **write** API is called to perform application event logging but the system ignores related event parameters because the value of the input event parameter is excessively long.
**Possible Causes**
The length of the input event parameter value exceeds 8 x 1024 characters.
**Solution**
Specify an event parameter value with a valid length.
## 11101005 Invalid Event Parameter Name
**Error Message**
Invalid event parameter name.
**Description**
This error code is reported if the **write** API is called to perform application event logging but the system ignores related event parameters because the input event parameter name is invalid.
**Possible Causes**
The specified event parameter name does not comply with the following rules:
- The event parameter name contains only digits, lowercase letters, and underscores (\_).
- The event parameter name starts with a lowercase letter and does not end with an underscore (\_).
- The event parameter name is not empty and contains a maximum of 16 characters.
**Solution**
Specify a valid event parameter name.
## 11101006 Invalid Array Length of Event Parameter Values
**Error Message**
Invalid array length of the event parameter.
**Description**
This error code is reported if the **write** API is called to perform application event logging but the system discards extra array elements because the array of the event parameter value is excessively long.
**Possible Causes**
The array length of the event parameter value exceeds 100.
**Solution**
Specify a valid array length for the event parameter value.
## 11102001 Invalid Watcher Name
**Error Message**
Invalid watcher name.
**Description**
This error code is reported if the **addWatcher** API is called to subscribe to application events but the system ignores the subscription because the specified watcher name is invalid.
**Possible Causes**
The specified watcher name does not comply with the following rules:
- The watcher name can contain only digits, lowercase letters, and underscores (\_).
- The watcher name starts with a lowercase letter and does not end with an underscore (\_).
- The watcher name is not empty and contains a maximum of 32 characters.
**Solution**
Specify a valid watcher name.
## 11102002 Invalid Filtering Event Domain Name
**Error Message**
Invalid filtering event domain.
**Description**
This error code is reported if the **addWatcher** API is called to subscribe to application events but the system ignores the subscription because the specified filtering event domain name is invalid.
**Possible Causes**
The specified filtering event domain name does not comply with the following rules:
- The event domain name contains only digits, lowercase letters, and underscores (\_).
- The event domain name starts with a lowercase letter and does not end with an underscore (\_).
- The event domain name is not empty and contains a maximum of 32 characters.
**Solution**
Specify a valid filtering event domain name.
## 11102003 Invalid Event Number
**Error Message**
Invalid row value.
**Description**
This error code is reported if the **addWatcher** API is called to subscribe to application events but the system ignores the subscription because an invalid event number is passed in the callback trigger condition.
**Possible Causes**
The event number passed in the input callback triggering condition is a negative number.
**Solution**
Specify a valid event number.
## 11102004 Invalid Event Size
**Error Message**
Invalid size value.
**Description**
This error code is reported if the **addWatcher** API is called to subscribe to application events but the system ignores the subscription because an invalid event size is passed in the callback trigger condition.
**Possible Causes**
The event size passed in the input callback triggering condition is a negative number.
**Solution**
Specify a valid event size.
## 11102005 Invalid Timeout Value
**Error Message**
Invalid timeout value.
**Description**
This error code is reported if the **addWatcher** API is called to subscribe to application events but the system ignores the subscription because an invalid timeout value is passed in the callback trigger condition.
**Possible Causes**
The timeout value passed in the input callback triggering condition is a negative number.
**Solution**
Specify a valid timeout value.
## 11103001 Invalid Maximum Storage Quota
**Error Message**
Invalid max storage quota value.
**Description**
This error code is reported if the **configure** API is called to subscribe to application events but the system ignores the setting because the specified maximum storage quota is invalid.
**Possible Causes**
The maximum storage quota does not meet the following rules:
- The quota value consists of only digits and a unit (including 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.
**Solution**
Specify a valid maximum storage quota.
## 11104001 Invalid Event Package Size
**Error Message**
Invalid size value.
**Description**
This error code is reported if the **setSize** API is called to set the threshold of the event package size but the system ignores the setting because the specified event package size is invalid.
**Possible Causes**
The specified event package size is a negative number.
@@ -24,6 +24,7 @@ The sandbox management module is available only for the standard system.
| src-path | Source path of the directory or file to mount.|
| sandbox-path | Target path in the sandbox.|
| sandbox-flags | Mount flag. The default value is **bind rec**.|
| ignore | Whether to ignore a mounting failure. If the value is set to 1, the system ignores the mounting failure and proceeds with the subsequent step. |
| target-name | Directory to link.|
| link-name | Target link in the sandbox.|
...
...
@@ -44,13 +45,13 @@ Logical storage structure of the sandbox:
boolInitSandboxWithName(constchar*name);// Parsing to the JSON structure
typedefstruct{
mountlist_t*mounts;// Directory to mount
mountlist_t*fileMounts;// File to mount
linklist_t*links;// Directory to link
char*rootPath;// Root path of the sandbox: /mnt/sandbox/system|vendor|xxx
charname[MAX_BUFFER_LEN];// Sandbox name, for example, system sandbox or chipset sandbox
boolisCreated;// Sandbox creation flag
intns;// namespace
ListNodepathMountsHead;// sandbox mount_path list head
ListNodefileMountsHead;// sandbox mount_file list head
ListNodelinksHead;// sandbox symbolic link list head
char*rootPath;// /mnt/sandbox/system|vendor|xxx
charname[MAX_BUFFER_LEN];// name of sandbox. i.e system, chipset etc.
