- Disabling the privacy flag: hdc_std shell hilog -p off
- Increasing the log buffer to 200 MB: hdc_std shell hilog -G 200M
- Enabling the log function of the specific domain (that is, disabling the global log function): hdc_std shell hilog –b D –D 0xd0xxxxx
After performing the preceding operations, restart the DevEco Studio.
## What should I do if the HAP installed on the development board through the IDE cannot be opened?
Applicable to: OpenHarmony SDK 3.2.5.3, stage model of API version 9
Check whether the SDK version is consistent with the system version on the development board. You are advised to use the SDK version and system version that are released on the same day.
## How do I upload files using the hdc command?
Applicable to: OpenHarmony SDK 3.2.2.5
Run the **hdc_std file send** command.
## How do I prevent the screen of the RK3568 development board from turning off?
Applicable to: OpenHarmony SDK 3.2.5.3, stage model of API version 9
Run the **hdc_std shell "power-shell setmode 602"** command.
## How do I start an ability using the hdc command?
Applicable to: OpenHarmony SDK 3.2.5.3, stage model of API version 9
Run the **hdc\_std shell aa start -a AbilityName -b bundleName -m moduleName** command.
## How do I change the read and write permissions on a file directory on the development board?
Applicable to: OpenHarmony SDK 3.2.5.6, stage model of API version 9
Run the **hdc\_std shell mount -o remount,rw /** command.
## What should I do if the error message "Unknown file option -r" is displayed when hdc_std file recv is run?
Applicable to: OpenHarmony SDK 3.2.5.6, stage model of API version 9
1. Use the the hdc tool in the device image or SDK of the same version.
2. Remove any Chinese characters or spaces from the directory specified for the hdc tool.
## How do I uninstall an application using the hdc command?
Applicable to: OpenHarmony SDK 3.2.2.5
Run the **hdc\_std uninstall [-k] [package_name]** command.
## How do I check whether the system is 32-bit or 64-bit?
Applicable to: OpenHarmony SDK 3.2.5.5
Run the **hdc\_std shell getconf LONG_BIT** command.
If **64** is returned, the system is a 64-bit one. Otherwise, the system is a 32-bit one.
## How do I view the component tree structure?
Applicable to: OpenHarmony SDK 3.2.5.5
1. Run the **hdc\_std shell** command to launch the CLI.
2. Run the **aa dump -a** command to find **abilityID**.
3. Run the **aa dump -i [abilityID] -c -render** command to view the component tree.
Initiates a call. This API uses an asynchronous callback to return the result.
>**NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [dialCall](#calldialcall9). The substitute API is available only for system applications.
Initiates a call. You can set call options as needed. This API uses an asynchronous callback to return the result.
>**NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [dialCall](#calldialcall9). The substitute API is available only for system applications.
Initiates a call. You can set call options as needed. This API uses a promise to return the result.
>**NOTE**
>
> This API is supported since API version 6 and deprecated since API version 9. You are advised to use [dialCall](#calldialcall9). The substitute API is available only for system applications.
The **hichecker** module is provided for you to check issues that may be easily ignored during development of OpenHarmony applications (including system-built and third-party applications). Such issues include calling of time-consuming functions by key application threads, event distribution and execution timeout in application processes, and ability resource leakage in application processes. The issues are recorded in logs or lead to process crashes explicitly so that you can find and rectify them.
The HiChecker module allows you to check issues that may be easily ignored during development of applications (including system-built and third-party applications). Such issues include calling of time-consuming functions by key application threads, event distribution and execution timeout in application processes, and ability resource leakage in application processes. The issues are recorded in logs or lead to process crashes explicitly so that you can find and rectify them.
> **NOTE**<br>
> **NOTE**
>
> 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.
> 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.
...
@@ -13,7 +14,7 @@ import hichecker from '@ohos.hichecker';
...
@@ -13,7 +14,7 @@ import hichecker from '@ohos.hichecker';
```
```
## Constant
## Constants
Provides the constants of all rule types.
Provides the constants of all rule types.
...
@@ -26,10 +27,8 @@ Provides the constants of all rule types.
...
@@ -26,10 +27,8 @@ Provides the constants of all rule types.
| RULE_THREAD_CHECK_SLOW_PROCESS | bigint | Caution rule, which is programmed to detect whether any time-consuming function is invoked. |
| RULE_THREAD_CHECK_SLOW_PROCESS | bigint | Caution rule, which is programmed to detect whether any time-consuming function is invoked. |
| RULE_CHECK_ABILITY_CONNECTION_LEAK | bigint | Caution rule, which is programmed to detect whether ability leakage has occurred. |
| RULE_CHECK_ABILITY_CONNECTION_LEAK | bigint | Caution rule, which is programmed to detect whether ability leakage has occurred. |
## hichecker.addCheckRule<sup>9+</sup>
## hichecker.addCheckRule<sup>9+</sup>
## hichecker.addRule
addCheckRule(rule: bigint): void
addCheckRule(rule: bigint): void
Adds one or more rules. HiChecker detects unexpected operations or gives feedback based on the added rules.
Adds one or more rules. HiChecker detects unexpected operations or gives feedback based on the added rules.
...
@@ -121,12 +120,12 @@ try {
...
@@ -121,12 +120,12 @@ try {
## hichecker.addRule<sup>(deprecated)</sup>
## hichecker.addRule<sup>(deprecated)</sup>
## hichecker.addRule
> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [hichecker.addCheckRule](#hicheckeraddcheckrule9) instead.
addRule(rule: bigint): void
addRule(rule: bigint): void
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [hichecker.addCheckRule](#hicheckeraddcheckrule9).
Adds one or more rules. HiChecker detects unexpected operations or gives feedback based on the added rules.
Adds one or more rules. HiChecker detects unexpected operations or gives feedback based on the added rules.
> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [hichecker.containsCheckRule](#hicheckercontainscheckrule9) instead.
> **NOTE**
>
> This API is deprecated since API version 9. You are advised to use [hichecker.containsCheckRule](#hicheckercontainscheckrule9).
Checks whether the specified rule exists in the collection of added rules. If the rule is of the thread level, this operation is performed only on the current thread.
Checks whether the specified rule exists in the collection of added rules. If the rule is of the thread level, this operation is performed only on the current thread.
@@ -363,7 +363,7 @@ Unregisters the observer for HTTP Response Header events.
...
@@ -363,7 +363,7 @@ Unregisters the observer for HTTP Response Header events.
>**NOTE**
>**NOTE**
>
>
>1. This API has been deprecated. You are advised to use [off('headersReceive')<sup>8+</sup>](#offheadersreceive8) instead.
>1. This API has been deprecated. You are advised to use [off('headersReceive')<sup>8+</sup>](#offheadersreceive8).
>
>
>2. You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.
>2. You can pass the callback of the **on** function if you want to cancel listening for a certain type of event. If you do not pass the callback, you will cancel listening for all events.
The **socket** module implements data transfer over TCPSocket, UDPSocket, WebSocket, and TLSSocket connections.
> **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.
> 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.
HiCollie provides the software watchdog function. It provides a unified framework for fault detection and fault log generation to help you locate software timeout faults resulting from system service deadlock, application main thread blocking, and service process timeout.
HiCollie provides the software watchdog function. It provides a unified framework for fault detection and fault log generation to help you locate software timeout faults resulting from system service deadlock, application main thread blocking, and service process timeout.
## Available APIs<a name="section139261151145116"></a>
| void RegisterXCollieChecker(const sptr<XCollieChecker>&checker, unsigned int type) | Registers the callback of the thread suspension detection result.<br>Input arguments:<br>- **checker**: pointer to the XCollieChecker instance.<br>- **type**: suspension detection type. Set it to **XCOLLIE_THREAD**.<br>Output arguments: none<br>Return value: none|
</td>
| int SetTimer(const std::string &name, unsigned int timeout, std::function<void(void*)> func, void *arg, unsigned int flag) | Adds timers.<br>Input arguments:<br>- **name**: timer name.<br>- **timeout**: timeout duration, in seconds.<br>- **func**: timeout callback.<br>- **arg**: pointer to the timeout callback.<br>- **flag**: timer operation type.<br> - **XCOLLIE_FLAG_DEFAULT**: default flag, which is the combination of the other three options.<br> - **XCOLLIE_FLAG_NOOP**: Calls only the timeout callback.<br> - **XCOLLIE_FLAG_LOG**: Generates a timeout fault log.<br> - **XCOLLIE_FLAG_RECOVERY**: Exits the process.<br>Output arguments: none<br>Return value: timer ID if the operation is successful; **-1** otherwise.|
<tdclass="cellrowborder"valign="top"width="44.47555244475552%"headers="mcps1.2.4.1.3 "><pid="p18700175062115"><aname="p18700175062115"></a><aname="p18700175062115"></a>Provides the callback of the suspension detection result.</p>
| bool UpdateTimer(int id, unsigned int timeout) | Updates timers.<br>Input arguments:<br>- **id**: timer ID.<br>- **timeout**: timeout duration, in seconds.<br>Output arguments: none<br>Return value: **true** if the operation is successful; **false** otherwise.|
<tdclass="cellrowborder"valign="top"width="44.47555244475552%"headers="mcps1.2.4.1.3 "><pid="p127630177475"><aname="p127630177475"></a><aname="p127630177475"></a>Provides the callback of the thread suspension detection result.</p>
<tdclass="cellrowborder"valign="top"width="35.82641735826417%"headers="mcps1.2.4.1.2 "><pid="p16289114074812"><aname="p16289114074812"></a><aname="p16289114074812"></a>void RegisterXCollieChecker(const sptr<XCollieChecker>&checker, unsigned int type)</p>
</td>
<tdclass="cellrowborder"valign="top"width="44.47555244475552%"headers="mcps1.2.4.1.3 "><pid="p186437319482"><aname="p186437319482"></a><aname="p186437319482"></a>Registers the callback of the thread suspension detection result.</p>
<aname="ul7783192181413"></a><aname="ul7783192181413"></a><ulid="ul7783192181413"><li><strongid="b64637561712"><aname="b64637561712"></a><aname="b64637561712"></a>checker</strong>: Indicates the pointer to the XCollieChecker instance.</li><li><strongid="b1947711661711"><aname="b1947711661711"></a><aname="b1947711661711"></a>type</strong>: Indicates the suspension detection type. Set it to <strongid="b259214119717"><aname="b259214119717"></a><aname="b259214119717"></a>XCOLLIE_THREAD</strong>.</li></ul>
<aname="ul845512153147"></a><aname="ul845512153147"></a><ulid="ul845512153147"><li><strongid="b44651010141715"><aname="b44651010141715"></a><aname="b44651010141715"></a>name</strong>: Indicates the timer name.</li><li><strongid="b266981221717"><aname="b266981221717"></a><aname="b266981221717"></a>timeout</strong>: Indicates the timeout duration, in seconds.</li><li><strongid="b17158171421710"><aname="b17158171421710"></a><aname="b17158171421710"></a>func</strong>: Indicates the timeout callback.</li><li><strongid="b1950162581810"><aname="b1950162581810"></a><aname="b1950162581810"></a>arg</strong>: Indicates the pointer to the timeout callback.</li><li><strongid="b4949151521714"><aname="b4949151521714"></a><aname="b4949151521714"></a>flag</strong>: Indicates the timer operation type.<pid="p1242762435310"><aname="p1242762435310"></a><aname="p1242762435310"></a>XCOLLIE_FLAG_DEFAULT // Indicates the default flag, which is the combination of the other three options.</p>
<pid="p1542712435312"><aname="p1542712435312"></a><aname="p1542712435312"></a>XCOLLIE_FLAG_NOOP // Calls only the timeout callback.</p>
<pid="p15427112416531"><aname="p15427112416531"></a><aname="p15427112416531"></a>XCOLLIE_FLAG_LOG // Generates a timeout fault log.</p>
<pid="p242762455314"><aname="p242762455314"></a><aname="p242762455314"></a>XCOLLIE_FLAG_RECOVERY // Exits the process.</p>
<pid="p144271424155316"><aname="p144271424155316"></a><aname="p144271424155316"></a>Return value: Returns the timer ID if the operation is successful; returns <strongid="b2229713291"><aname="b2229713291"></a><aname="b2229713291"></a>-1</strong> otherwise.</p>
<aname="ul1628783221411"></a><aname="ul1628783221411"></a><ulid="ul1628783221411"><li><strongid="b61651021161710"><aname="b61651021161710"></a><aname="b61651021161710"></a>id</strong>: Indicates the timer ID.</li><li><strongid="b24661423141717"><aname="b24661423141717"></a><aname="b24661423141717"></a>timeout</strong>: Indicates the timeout duration, in seconds.</li></ul>
<pid="p38311853105716"><aname="p38311853105716"></a><aname="p38311853105716"></a>Return value: Returns <strongid="b95701352192819"><aname="b95701352192819"></a><aname="b95701352192819"></a>true</strong> if the operation is successful; returns <strongid="b175761652152814"><aname="b175761652152814"></a><aname="b175761652152814"></a>false</strong> otherwise.</p>
<pid="p9311488283"><aname="p9311488283"></a><aname="p9311488283"></a><strongid="b9666749171816"><aname="b9666749171816"></a><aname="b9666749171816"></a>id</strong>: Indicates the timer ID.</p>
This function requires you to implement two callback functions: **CheckBlock** and **CheckThreadBlock** of the **XCollieChecker** class. After the callbacks are implemented, you need to use the **RegisterXCollieChecker** function of the **XCollie** class to register their instances. The suspension monitoring thread periodically executes all successfully registered callbacks, checks the thread logic completion flag, and determines whether the service logic of any registered thread is suspended.
This function requires you to implement two callback functions: **CheckBlock** and **CheckThreadBlock** of the **XCollieChecker** class. After the callbacks are implemented, you need to use the **RegisterXCollieChecker** function of the **XCollie** class to register their instances. The suspension monitoring thread periodically executes all successfully registered callbacks, checks the thread logic completion flag, and determines whether the service logic of any registered thread is suspended.
1. Develop the source code.
1. Develop the source code.
Include the **xcollie** header file in the source file.
Include the **xcollie** header file in the source file.
```
```
...
@@ -124,6 +42,7 @@ This function requires you to implement two callback functions: **CheckBlock**
...
@@ -124,6 +42,7 @@ This function requires you to implement two callback functions: **CheckBlock**
Add the following code to the service code:
Add the following code to the service code:
```
```
void MyXCollieChecker::CheckLock()
void MyXCollieChecker::CheckLock()
{
{
...
@@ -138,7 +57,7 @@ This function requires you to implement two callback functions: **CheckBlock**
...
@@ -138,7 +57,7 @@ This function requires you to implement two callback functions: **CheckBlock**
sptr<XCollieChecker> checker = new MyXCollieChecker("MyXCollieChecker");
sptr<XCollieChecker> checker = new MyXCollieChecker("MyXCollieChecker");
You can add a maximum of 128 timers for a single process by using the **SetTimer** function. Adding timers will fail if the number of timers has reached the upper limit.
You can add a maximum of 128 timers for a single process by using the **SetTimer** function. Adding timers will fail if the number of timers has reached the upper limit.
1. Develop the source code.
1. Develop the source code.
Include the **xcollie** header file in the source file.
Include the **xcollie** header file in the source file.
```
```
...
@@ -173,7 +91,7 @@ You can add a maximum of 128 timers for a single process by using the **SetTime
...
@@ -173,7 +91,7 @@ You can add a maximum of 128 timers for a single process by using the **SetTime
XCollie::GetInstance().UpdateTimer(id, 5);
XCollie::GetInstance().UpdateTimer(id, 5);
/* time consuming job */
/* time consuming job */
XCollie::GetInstance().CancelTimer(id);
XCollie::GetInstance().CancelTimer(id);
...
......
```
```
2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**.
2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**.
...
@@ -181,5 +99,3 @@ You can add a maximum of 128 timers for a single process by using the **SetTime
...
@@ -181,5 +99,3 @@ You can add a maximum of 128 timers for a single process by using the **SetTime
HiDumper is a tool provided by OpenHarmony for developers, testers, and IDE tool engineers to obtain system information necessary for analyzing and locating faults. This section applies only to the standard system.
HiDumper is a tool provided by OpenHarmony for developers, testers, and IDE tool engineers to obtain system information necessary for analyzing and locating faults. This section applies only to the standard system.
### Source Code Directories
## Source Code Directories
```
```
...
@@ -34,14 +31,14 @@ HiDumper is a tool provided by OpenHarmony for developers, testers, and IDE tool
...
@@ -34,14 +31,14 @@ HiDumper is a tool provided by OpenHarmony for developers, testers, and IDE tool
```
```
## Usage
# Usage
### Command-Line Options
## Command-Line Options
**Table 1** HiDumper command-line options
**Table 1** HiDumper command-line options
| Option| Description|
| Option| **Description**|
| -------- | -------- |
| -------- | -------- |
| -h | Shows the help Information.|
| -h | Shows the help Information.|
| -t [timeout] | Specifies the timeout period, in seconds. The default value is **30**. Value **0** indicates no timeout limit.|
| -t [timeout] | Specifies the timeout period, in seconds. The default value is **30**. Value **0** indicates no timeout limit.|
...
@@ -56,14 +53,14 @@ HiDumper is a tool provided by OpenHarmony for developers, testers, and IDE tool
...
@@ -56,14 +53,14 @@ HiDumper is a tool provided by OpenHarmony for developers, testers, and IDE tool
| --net | Exports network information.|
| --net | Exports network information.|
| --storage | Exports storage information.|
| --storage | Exports storage information.|
| -p | Exports the process list and all process information.|
| -p | Exports the process list and all process information.|
| -p [pid] | Exports all information about a specified process.|
| -p [pid] | Exports all information about the specified process.|
| --cpuusage [pid] | Exports the CPU usage information based on **pid**.|
| --cpuusage [pid] | Exports the CPU usage information. If **pid** is specified, the CPU usage of the corresponding process is exported.|
| --cpufreq | Exports the actual CPU frequency.|
| --cpufreq | Exports the actual CPU frequency.|
| --mem [pid] | Exports the memory usage information based on **pid**.|
| --mem [pid] | Export memory usage information. If **pid** is specified, the memory usage of the corresponding process is exported.|
| --zip | Compresses the exported information to a specified folder.|
| --zip | Compresses the exported information to a specified folder.|
### Development Example
## Development Example
HiDumper helps you export basic system information to locate and analyze faults. Complex parameters passed to sub-services and abilities must be enclosed in double quotation marks.
HiDumper helps you export basic system information to locate and analyze faults. Complex parameters passed to sub-services and abilities must be enclosed in double quotation marks.
...
@@ -118,7 +115,7 @@ The procedure is as follows:
...
@@ -118,7 +115,7 @@ The procedure is as follows:
hidumper -s 3008
hidumper -s 3008
```
```
9. Run the **hidumper -e** command to obtain the crash information generated by the FaultLogger module.
9. Run the **hidumper -e** command to obtain the crash information generated by the FaultLoger module.
```
```
hidumper -e
hidumper -e
...
@@ -148,7 +145,7 @@ The procedure is as follows:
...
@@ -148,7 +145,7 @@ The procedure is as follows:
hidumper -p 1024
hidumper -p 1024
```
```
14. Run the **hidumper --cpuusage [pid]** command to obtain the CPU usage information of the process whose PID has been specified.
14. Run the **hidumper --cpuusage [pid]** command to obtain the CPU usage information. If the PID of a process is specified, only the CPU usage of the process is returned.
```
```
hidumper --cpuusage
hidumper --cpuusage
...
@@ -161,7 +158,7 @@ The procedure is as follows:
...
@@ -161,7 +158,7 @@ The procedure is as follows:
hidumper --cpufreq
hidumper --cpufreq
```
```
16. Run the **hidumper --mem [pid]** command to obtain all memory usage information of the process whose PID has been specified.
16. Run the **hidumper --mem [pid]** command to obtain all memory usage information. If the PID of a process is specified, only the memory usage of the process is returned.
HiTraceMeter is the OpenHarmony subsystem that provides APIs to implement call chain trace throughout a service process. With HiTraceMeter, you can quickly obtain the run log specific to the call chain of a service process and locate faults in inter-device, inter-process, or inter-thread communications. HiTraceMeter supports event logging in user mode and can collect trace data in user mode and kernel mode for performance tracing and analysis.
HiTraceMeter is the OpenHarmony subsystem that provides APIs to implement call chain trace throughout a service process. With HiTraceMeter, you can quickly obtain the run log specific to the call chain of a service process and locate faults in inter-device, inter-process, or inter-thread communications. HiTraceMeter supports event logging in user mode and can collect trace data in user mode and kernel mode for performance trace and analysis.
## Basic Concepts
## Basic Concepts
The HiTraceMeter subsystem consists of three parts:
The HiTraceMeter subsystem consists of three parts:
- JS/C++ HiTraceMeter APIs for application logging
- JS/C++ HiTraceMeter APIs for application logging
- hitrace CLI tool for data collection
- hitrace CLI tool for data collection
- smartperf tool for graphical data analysis
- smartperf tool for graphical data analysis
Wherein, HiTraceMeter APIs and the hitrace CLI tool run on the device side, and the smartperf tool runs on the PC side. HiTraceMeter APIs are provided in C++ and JS for event logging, which aims to generate the trace data necessary for performance tracing and analysis during the development process.
Wherein, HiTraceMeter APIs and the hitrace CLI tool run on the device side, and the smartperf tool runs on the PC side. HiTraceMeter APIs are provided in C++ and JS for event logging, which aims to generate the trace data necessary for performance trace and analysis during the development process.
The hitrace CLI tool is used to collect trace data. It captures trace data flows and saves the data as a text file.
The hitrace CLI tool is used to collect trace data. It captures trace data flows and saves the data as a text file.
...
@@ -80,7 +81,6 @@ HiTraceMeter provides the hitrace CLI tool for capturing trace data in user mode
...
@@ -80,7 +81,6 @@ HiTraceMeter provides the hitrace CLI tool for capturing trace data in user mode
## Constraints
## Constraints
- The implementation of HiTraceMeter functions and APIs depends on the ftrace functionality, a framework provided by the kernel. It enables developers to add more trace functions via plug-ins. Therefore, make sure that ftrace is enabled before you use HiTraceMeter.
- The implementation of HiTraceMeter functions and APIs depends on the ftrace functionality, a framework provided by the kernel. It enables developers to add more trace functions via plug-ins. Therefore, make sure that ftrace is enabled before you use HiTraceMeter.
...
@@ -95,7 +95,6 @@ HiTraceMeter development focuses on two parts: JS/C++ event logging APIs and the
...
@@ -95,7 +95,6 @@ HiTraceMeter development focuses on two parts: JS/C++ event logging APIs and the
## When to Use
## When to Use
You may encounter unexpected issues like app freezing during app development or need to view the code's call chain during code debugging. With the APIs provided by HiTraceMeter, you'll be able to trace the application delay and call chain to identify performance problems.
You may encounter unexpected issues like app freezing during app development or need to view the code's call chain during code debugging. With the APIs provided by HiTraceMeter, you'll be able to trace the application delay and call chain to identify performance problems.
...
@@ -106,18 +105,17 @@ Only C++ APIs are now open for system developers. If you're developing a JS app,
...
@@ -106,18 +105,17 @@ Only C++ APIs are now open for system developers. If you're developing a JS app,
| void StartTrace(uint64_t label, const std::string& value, float limit = -1); | Starts a synchronous trace.|**label**: trace category.<br>**value**: trace data that indicates the specific status, such as the memory size and queue length.|
| void StartTrace(uint64_t label, const std::string& value, float limit = -1); | Starts a synchronous trace.| **label**: trace category.<br>**value**: trace data that indicates the specific status, such as the memory size and queue length.|
**StartTrace** and **FinishTrace** must be used in pairs, and **FinishTrace** matches the latest **StartTrace**. The two APIs can be used in nested mode. The stack data structure is used for matching during trace data parsing. The **limit** parameter is used for flow control, and you are advised to use the default value.
**StartTrace** and **FinishTrace** must be used in pairs, and **FinishTrace** matches the latest **StartTrace**. The two APIs can be used in nested mode. The stack data structure is used for matching during trace data parsing. The **limit** parameter is used for flow control, and you are advised to use the default value.
**Table 2** Async APIs
**Table 2** Async APIs
| Async trace | Function |Parameter Description |
| Async trace | Function | Parameter Description |
| void StartAsyncTrace(uint64_t label, const std::string& value, int32_t taskId, float limit = -1); | Starts an asynchronous trace.| **label**: trace category.<br>**value**: trace data that indicates the specific status, such as the memory size and queue length.<br>**taskId**: ID used to indicate the association of APIs in an asynchronous trace.|
| void StartAsyncTrace(uint64_t label, const std::string& value, int32_t taskId, float limit = -1); | Starts an asynchronous trace.| **label**: trace category.<br>**value**: trace data that indicates the specific status, such as the memory size and queue length.<br>**taskId**: ID used to indicate the association of APIs in an asynchronous trace.|
| void FinishAsyncTrace(uint64_t label, const std::string& value, int32_t taskId); | Stops an asynchronous trace.| **label**: trace category.<br>**value**: trace data that indicates the specific status, such as the memory size and queue length.<br>**taskId**: ID used to indicate the association of APIs in an asynchronous trace.|
| void FinishAsyncTrace(uint64_t label, const std::string& value, int32_t taskId); | Stops an asynchronous trace.| **label**: trace category.<br>**value**: trace data that indicates the specific status, such as the memory size and queue length.<br>**taskId**: ID used to indicate the association of APIs in an asynchronous trace.|
...
@@ -127,17 +125,18 @@ The trace data of **StartAsyncTrace** and **FinishAsyncTrace** is matched based
...
@@ -127,17 +125,18 @@ The trace data of **StartAsyncTrace** and **FinishAsyncTrace** is matched based
**Table 3** Counter APIs
**Table 3** Counter APIs
| Counter Trace | Function |Parameter Description |
| Counter Trace | Function | Parameter Description |
| void CountTrace(uint64_t label, const std::string& name, int64_t); | Count trace.|**label**: trace category.<br>**name**: trace name displayed in the IDE.|
| void CountTrace(uint64_t label, const std::string& name, int64_t); | Count trace.| **label**: trace category.<br>**name**: trace name displayed in the IDE.|
## How to Develop
## How to Develop
1. Add the build dependencies to the build configuration file **base\hiviewdfx\hitrace\cmd\BUILD.gn**.
1. Add the build dependencies to the build configuration file **base\hiviewdfx\hitrace\cmd\BUILD.gn**.
```
```
external_deps = [ "hitrace_native:hitrace_meter"]
external_deps = [ "hitrace_native:hitrace_meter"]
```
```
2. Add the header file dependencies.
2. Add the header file dependencies.
```cpp
```cpp
...
@@ -146,13 +145,12 @@ The trace data of **StartAsyncTrace** and **FinishAsyncTrace** is matched based
...
@@ -146,13 +145,12 @@ The trace data of **StartAsyncTrace** and **FinishAsyncTrace** is matched based
3. When calling an API, pass the trace value as an input parameter. The trace tags currently supported are listed in **hitrace_meter.h**. Assume that the trace tag is **OHOS** and trace data of **func1** and **func2** needs to be captured. After the hitrace command is executed in the shell, the trace data is automatically captured. The captured data includes the function call process and the memory and time consumed during this process. You can use the data to analyze the call process to identify performance problems.
3. When calling an API, pass the trace value as an input parameter. The trace tags currently supported are listed in **hitrace_meter.h**. Assume that the trace tag is **OHOS** and trace data of **func1** and **func2** needs to be captured. After the hitrace command is executed in the shell, the trace data is automatically captured. The captured data includes the function call process and the memory and time consumed during this process. You can use the data to analyze the call process to identify performance problems.
```cpp
#include "hitrace_meter.h" // Include hitrace_meter.h
usingnamespacestd;
```cpp
intmain()
#include "hitrace_meter.h" // Include hitrace_meter.h
FinishTrace(label);// Trace end point of func1Trace
FinishTrace(label);// Trace end point of func1Trace
StartAsyncTrace(label,"asyncTrace1",1234);// Trace start point of asyncTrace1
StartAsyncTrace(label,"asyncTrace1",1234);// Trace start point of asyncTrace1
FinishAsyncTrace(label,"asyncTrace1",1234);// Trace end point of asyncTrace2
FinishAsyncTrace(label,"asyncTrace1",1234);// Trace end point of asyncTrace1
return0;
return0;
}
}
...
@@ -180,7 +178,6 @@ int main()
...
@@ -180,7 +178,6 @@ int main()
You can open the captured data by clicking **Open trace file** in the smartperf tool or dragging the data to the graphics area. For details, see [smartperf](https://toscode.gitee.com/openharmony-sig/smartperf).
You can open the captured data by clicking **Open trace file** in the smartperf tool or dragging the data to the graphics area. For details, see [smartperf](https://toscode.gitee.com/openharmony-sig/smartperf).
## Verification
## Verification
The following is a demo debugging process, where the **StartTrace** and **FinishTrace** APIs are used in synchronization mode.
The following is a demo debugging process, where the **StartTrace** and **FinishTrace** APIs are used in synchronization mode.
...
@@ -274,10 +271,10 @@ The hitrace CLI tool is an executable binary program. On an OpenHarmony-powered
...
@@ -274,10 +271,10 @@ The hitrace CLI tool is an executable binary program. On an OpenHarmony-powered
| -b *n*, --buffer_size *n* | Sets the buffer size for trace data in KB. The default value is **2048**. |
| -b *n*, --buffer_size *n* | Sets the buffer size for trace data in KB. The default value is **2048**. |
| -t *n*, --time *n* | Sets the trace uptime in seconds, which depends on the time required for analysis.|
| -t *n*, --time *n* | Sets the trace uptime in seconds, which depends on the time required for analysis.|
| --trace_clock clock | Sets the type of the clock for adding a timestamp to a trace. The value can be **boot** (default), **global**, **mono**, **uptime**, or **perf**.|
| --trace_clock clock | Sets the type of the clock for adding a timestamp to a trace. The value can be **boot** (default), **global**, **mono**, **uptime**, or **perf**.|
| --trace_begin | Starts capturing trace data. |
| --trace_begin | Starts capturing trace data. |
| --trace_dump | Dumps trace data to the specified position. The default position is the console. |
| --trace_dump | Dumps trace data to the specified position. The default position is the console. |
...
@@ -292,34 +289,41 @@ Examples:
...
@@ -292,34 +289,41 @@ Examples:
- Query supported labels.
- Query supported labels.
```
```
hitrace -l
hitrace -l
```
```
Alternatively, run the following command:
Alternatively, run the following command:
```
```
hitrace --list_categories
hitrace --list_categories
```
```
- Trace ability information for 10 seconds and store the trace data in a buffer of 4 MB.
- Trace ability information for 10 seconds and store the trace data in a buffer of 4 MB.
The data captured by running the hitrace command is incomplete or no data is captured.
The data captured by running the hitrace command is incomplete or no data is captured.
#### **Root Cause**
The value of **-t** or **-b** buffer is too small, leading to data loss.
#### Solution
#### Solution
Check the value of the **-t** and **-b** parameters. If the value is too small, data loss will occur. You are advised to set **-t** to **60** and **-b** to **204800** to increase the trace capture time and buffer, respectively.
You can set **-t** to **60** and **-b** to **204800** to increase the trace time and buffer size.
# Reference
# Reference
For details about HiTraceMeter, see [hiviewdfx_hitrace: A Lightweight Distributed Tracing](https://gitee.com/openharmony/hiviewdfx_hitrace).
For details about HiTraceMeter, see [hiviewdfx_hitrace: Lightweight Distributed Trace](https://gitee.com/openharmony/hiviewdfx_hitrace).
[Design for X](https://en.wikipedia.org/wiki/Design_for_X)\(DFX\) refers to the software design that aims to improve the quality attributes in OpenHarmony. It mainly consists of two parts: design for reliability \(DFR\) and design for testability \(DFT\).
[Design for X](https://en.wikipedia.org/wiki/Design_for_X)\(DFX\) refers to the software design that aims to improve the quality attributes in OpenHarmony. It mainly consists of two parts: design for reliability \(DFR\) and design for testability \(DFT\).
The DFX subsystem provides the following functions:
The DFX subsystem provides the following functions:
- HiLog: implements the logging function. It is applicable to mini-system devices \(reference memory ≥ 128 KiB\), small-system devices \(reference memory ≥ 1 MiB\), and standard-system devices \(reference memory ≥ 128 MB\).
- HiLog: implements the logging function. It is applicable to mini-system devices \(reference memory ≥ 128 KiB\), small-system devices \(reference memory ≥ 1 MiB\), and standard-system devices \(reference memory ≥ 128 MiB\).
- HiTraceChain: implements distributed call chain tracing. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- HiTraceChain: implements distributed call chain trace. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- HiTraceMeter: implements performance trace. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- HiTraceMeter: implements performance trace. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- HiCollie: implements thread suspension detection. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- HiCollie: implements thread suspension detection. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- HiSysEvent: implements system event logging. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- HiSysEvent: implements system event logging. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- HiDumper: exports system information. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- HiDumper: exports system information. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- FaultLogger: implements crash detection. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- Faultlogger: implements crash detection. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- Hiview: implements device maintenance across different platforms. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- Hiview: implements device maintenance across different platforms. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- HiAppEvent and HiChecker are only hap developer oriented。
- HiAppEvent and HiChecker are applicable only for HAP developers.
Logging means to record the log information generated during system running so you can understand the running process and status of the system or applications.
Logging means to record the log information generated during system running so you can understand the running process and status of the system or applications.
**Distributed call chain tracing**
**Distributed call chain trace**
In a distributed system, the initiation of a service may involve multiple software modules, with control commands and data transmitted over intra-process, inter-process, and inter-device communication interfaces. To help you understand such complex communication processes and locate service faults efficiently, the DFX subsystem provides a distributed call chain tracing framework.
In a distributed system, the initiation of a service may involve multiple software modules, with control commands and data transmitted over intra-process, inter-process, and inter-device communication interfaces. To help you understand such complex communication processes and locate service faults efficiently, the DFX subsystem provides a distributed call chain trace framework.
**Thread suspension detection**
**Thread suspension detection**
If a thread is trapped in an infinite loop or the kernel state \(for example, Uninterruptable Sleep, Traced, Zombie, or synchronous wait\) when it is running, the thread cannot respond to normal service requests and cannot detect and recover from faults by itself. To detect and locate this type of faults, the DFX subsystem provides a simple watchdog mechanism by inserting detection probes to the process nodes that are prone to suspension. This ensures that suspension faults can be detected and logs can be collected.
If a thread is trapped in an infinite loop or the kernel state (for example, Uninterruptable Sleep, Traced, Zombie, or synchronous wait) when it is running, the thread cannot respond to normal service requests and cannot detect and recover from faults by itself. To detect and locate this type of faults, the DFX subsystem provides a simple watchdog mechanism by inserting detection probes to the process nodes that are prone to suspension. This ensures that suspension faults can be detected and logs can be collected.
**Event logging**
**Logging**
Event logging means to collect and log events reported during system running. The log information will help you better analyze the product usage.
Event logging means to collect and log events reported during system running. The log information will help you better analyze the product usage.
**System event**
**System event**
A system event is an indication of the system status at a given time point during system running. You can use these events to analyze the status change of the system.
A system event is an indication of the system status at a given time point during system running. You can use these events to analyze the status change of the system.
