@@ -37,18 +37,15 @@ No error will be thrown if the preceding APIs are used in the troubleshooting sc
### Application State Management
Since API version 10, application recovery is not limited to automatic restart in the case of an exception. Therefore, you need to understand when the application will load the saved state.
If the last exit of an application is not initiated by a user and a saved state is available for recovery, the startup reason is set to **APP_RECOVERY** when the application is started by the user next time, and the recovery state of the application is cleared.
The application recovery status flag is set when **saveAppState** is actively or passively called. The flag is cleared when the application exits normally or the saved state is consumed. (A normal exit is usually triggered by pressing the back key or clearing recent tasks.)
### Application State Saving and Restore
API version 10 or later supports saving of the application state when an application is suspended. If a JsError occurs, **onSaveState** is called in the main thread. If an AppFreeze occurs, however, the main thread may be suspended, and therefore **onSaveState** is called in a non-main thread. The following figure shows the main service flow.
When the application is suspended, the callback is not executed in the JS thread. Therefore, you are advised not to use the imported dynamic Native library or access the **thread_local** object created by the main thread in the code of the **onSaveState** callback.
### Framework Fault Management
...
...
@@ -62,13 +59,9 @@ Fault management is an important way for applications to deliver a better user e
- Fault query is the process of calling APIs of [faultLogger](../reference/apis/js-apis-faultLogger.md) to obtain the fault information.
The figure below does not illustrate the time when [faultLogger](../reference/apis/js-apis-faultLogger.md) is called. You can refer to the [LastExitReason](../reference/apis/js-apis-app-ability-abilityConstant.md#abilityconstantlastexitreason) passed during application initialization to determine whether to call [faultLogger](../reference/apis/js-apis-faultLogger.md) to query information about the previous fault.
It is recommended that you call [errorManager](../reference/apis/js-apis-app-ability-errorManager.md) to handle the exception. After the processing is complete, you can call the **saveAppState** API and restart the application.
If you do not register [ErrorObserver](../reference/apis/js-apis-inner-application-errorObserver.md) or enable application recovery, the application process will exit according to the default processing logic of the system. Users can restart the application from the home screen.
If you have enabled application recovery, the recovery framework first checks whether application state saving is supported and whether the application state saving is enabled. If so, the recovery framework invokes [onSaveState](../reference/apis/js-apis-app-ability-uiAbility.md#uiabilityonsavestate) of the [Ability](../reference/apis/js-apis-app-ability-uiAbility.md). Finally, the application is restarted.
FaultLogger is a maintenance and debugging log framework provided by OpenHarmony. It enables unified detection, log collection, log storage, and log reporting for application, ability, and system service process crashes. It is available for the standard system and the Linux kernel-based small system.
FaultLogger is responsible for fault recording of OpenHarmony. It runs on the following two components based on the service object:
- HiView: serves functional modules at the application layer and native layer. It manages various fault information in the system and provides APIs for modules to query faults.
- Hiview: serves functional modules at the application layer and native layer. It manages various fault information in the system and provides APIs for modules to query faults.
- FaultLoggerd: serves the crash process. It collects information about abnormal daemon processes in C/C++ and obtains the process call stack.
- Faultloggerd: serves the crash process. It collects information about the abnormal daemon process in C/C++ and obtains call stack information of the process.
The following figure shows the process of handling a process crash based on the FaultLogger service.
1. After the signal processor is installed, the **DFX_SignalHandler** function detects and responds to the process crash exception signal.
1. After the signal processor is installed, SignalHandler uses the **DFX_SignalHandler** function to detect and respond to the process crash exception signal thrown by the kernel.
2.**SignalHandler** forks a child process after detecting the exception signal and runs **ProcessDump** to dump the stack information of the crashed process and thread.
2.When detecting a process crash exception signal, SignalHandler forks a child process and runs ProcessDump to dump the stack information of the crashed process and thread.
3.**ProcessDump** then writes a log to the temporary storage directory in FaultLoggerd, generating a full crash log.
3.ProcessDump applies to Faultloggerd for a file handle for storing fault logs. After reading the exception stack information, ProcessDump writes the information to the file to generate a complete crash log.
4.FaultLoggerd reports the fault through the **AddFaultLog()** API provided by HiView. HiView handles the fault, generates a simple crash log, and reports a HiSysEvent.
4.After collecting the complete crash log, ProcessDump reports the log to Hiview by using the **AddFaultLog()** API. Hiview generates a simplified crash log and reports a system event through HiSysEvent.
With this design, a small-system with limited resources can obtain logs for locating crash faults as long as FaultLoggerd is deployed.
With this design, a small-system with limited resources can obtain logs for locating crash faults as long as Faultloggerd is deployed.
### Use Cases
FaultLoggerd provides a lightweight approach for you to locate crash or suspension problems during development and testing.
Faultloggerd provides a lightweight approach for you to locate crash or suspension problems during development and testing.
It is applicable to the following scenarios:
The following table describes the application scenarios.
**Table 1** Application scenarios of the Faultloggerd module
| Scenario| Tool| Usage|
| Scenario| Tool| Usage|
| -------- | -------- | -------- |
| To understand the function call sequence| DumpCatcher API | See [Using DumpCatcher to Obtain the Call Stack](#using-dumpcatcher-to-obtain-the-call-stack).|
| Application suspension or high CPU usage| ProcessDump | See [Using ProcessDump to Obtain the Call Stack](#using-processdump-to-obtain-the-call-stack).|
| Signal crash not handled by the process| Crash log and addr2line tool| See [Locating Faults Based on Crash Logs](#locating-faults-based-on-crash-logs).|
| Understanding of the function call sequence| DumpCatcher API | See [Using DumpCatcher APIs to Obtain Call Stack Information](#using-dumpcatcher-apis-to-obtain-call-stack-information).|
| Application suspension or high CPU usage| DumpCatcher Command Tool | See [Using DumpCatcher Commands to Obtain Call Stack Information](#using-dumpcatcher-commands-to-obtain-call-stack-information).|
| Crash fault location| Crash log and addr2line tool| For details, see [Locating Faults Based on the Crash Log](#locating-faults-based-on-the-crash-log).|
## Using DumpCatcher to Obtain the Call Stack
## Using DumpCatcher APIs to Obtain the Call Stack Information
### Available APIs
DumpCatcher can capture the call stack of a specified process (thread) on OpenHarmony.
DumpCatcher can capture the call stack information of the specified process (thread) on OpenHarmony.
Table 2 DumpCatcher APIs
**Table 2** DumpCatcher APIs
| Class| API| Description|
| Class| API| Description|
| -------- | -------- | -------- |
| DfxDumpCatcher | bool DumpCatch(const int pid, const int tid, std::string& msg) | Return value:<br>**true**: Back trace is successful. Related information is stored in the **msg** string object.<br>**false**: Back trace failed.<br>Input arguments:<br>**pid**: target process ID.<br>**tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.<br>Output argument:<br>**msg**: return message. If back trace is successful, the call stack information is returned through **msg**.|
| DfxDumpCatcher | bool DumpCatch(const int pid, const int tid, std::string& msg) | Return value:<br>- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.<br>- **false**: Dumping of stack information has failed.<br> Input arguments:<br>- **pid**: target process ID.<br>- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.<br> Output arguments:<br>- **msg**: If back trace is successful, call stack information is returned through **msg**.|
| DfxDumpCatcher | bool DumpCatchMix(const int pid, const int tid, std::string& msg) | Return value:<br>- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.<br>- **false**: Dumping of stack information has failed.<br> Input arguments:<br>**pid**: target process ID.<br>- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.<br> Output arguments:<br>- **msg**: If back trace is successful, hybrid stack information is returned through **msg**.|
| DfxDumpCatcher | bool DumpCatchFd(const int pid, const int tid, std::string& msg, int fd) | Return value:<br>- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.<br>- **false**: Dumping of stack information has failed.<br> Input arguments:<br>**pid**: target process ID.<br>- **tid**: target thread ID. If all threads in the process need to be back traced, set **tid** to **0**.<br>- **fd**: handle of the file to be written.<br> Output parameters:<br>- **msg**: If back trace is successful, call stack information is returned through **msg**.|
| DfxDumpCatcher | bool DumpCatchMultiPid(const std::vector\<int> pidV, std::string& msg) | Return value:<br>- **true**: Dumping of stack information is successful. Related information is stored in the msg string object.<br>- **false**: Dumping of stack information has failed.<br> Input arguments:<br>- **pidV**: target process ID list.<br> Output arguments:<br>- **msg**: If back trace is successful, call stack information is returned through **msg**.|
> If the PID that calls this API is different from the target PID, the caller must be the **system** or **root** user. To capture the call stack of a process that does not belong to the current user group, ensure that you have permissions to read **/proc/pid/maps** and implement **ptrace** on the peer process.
> **NOTE**
> If the PID that calls this API is different from the target PID, the caller must be the **system** or **root** user.
### Development Example
### How to Develop
You can use DumpCatcher to obtain call stack information for the specified process (thread) of an application. The following uses the **dumpcatcherdemo** module as an example to describe how to use the DumpCatcher APIs to obtain the call stack information.
You can use DumpCatcher to obtain the call stack of a specified process (thread) in your applications. The following uses the **dumpcatcherdemo** module as an example to describe how to use the DumpCatcher API to obtain the call stack.
1. Add the DumpCatcher dependency to the build file. Take /base/hiviewdfx/faultloggerd/example/BUILD.gn as an example. Add the **dump_catcher.h** file path to **include_dirs** and add the required **//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:lib_dfx_dump_catcher** module to **deps**.
1. Add the DumpCatcher dependency to the build file. Take /base/hiviewdfx/faultloggerd/example/BUILD.gn as an example. Add the **dfx_dump_catcher.h** file path to **include_dirs** and add the required **//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:lib_dfx_dump_catcher** module to **deps**.
"//base/hiviewdfx/faultloggerd/interfaces/innerkits/dump_catcher:lib_dfx_dump_catcher", # Add the DumpCatcher module dependency.
"//utils/native/base:utils",
]
external_deps = [ "hilog_native:libhilog" ]
install_enable = true
part_name = "faultloggerd"
subsystem_name = "hiviewdfx"
}
```
2. Define the header file. Take **/base/hiviewdfx/faultloggerd/example/dump_catcher_demo.h** as an example. In the sample code, the function of the stack depth test is called to construct a call stack with a specified depth.
```
#ifndef DUMP_CATCHER_DEMO_H
#define DUMP_CATCHER_DEMO_H
#include <inttypes.h>
#define NOINLINE __attribute__((noinline))
// Define the macro function to automatically generate a function call chain.
#define GEN_TEST_FUNCTION(FuncNumA, FuncNumB) \
__attribute__((noinline)) int TestFunc##FuncNumA() \
{ \
return TestFunc##FuncNumB(); \
}
// Call the function of the stack depth test.
int TestFunc0(void);
int TestFunc1(void);
...
...
@@ -118,33 +131,33 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread)
int TestFunc8(void);
int TestFunc9(void);
int TestFunc10(void);
#endif // DUMP_CATCHER_DEMO_H
```
3. Call the **DumpCatch** API in the source file. Take **/base/hiviewdfx/faultloggerd/example/dump_catcher_demo.cpp** as an example. Include the **dfx_dump_catcher.h** file, declare the **DfxDumpCatcher** object, use the macro function to construct a function call chain, call the **DumpCatch** method, and pass the required process ID and thread ID of the call stack into this method.
```
#include "dump_catcher_demo.h"
#include <iostream>
#include <string>
#include <unistd.h>
// Include the dfx_dump_catcher.h file.
#include "dfx_dump_catcher.h"
using namespace std;
NOINLINE int TestFunc10(void)
{
OHOS::HiviewDFX::DfxDumpCatcher dumplog;
string msg = "";
bool ret = dumplog.DumpCatch(getpid(), gettid(), msg); // Call the DumpCatch API to obtain the call stack.
bool ret = dumplog.DumpCatch(getpid(), gettid(), msg); // Call the DumpCatch API to obtain the call stack information.
if (ret) {
cout << msg << endl;
}
return 0;
}
// Use the macro function to automatically generate a function call chain.
GEN_TEST_FUNCTION(0, 1)
GEN_TEST_FUNCTION(1, 2)
...
...
@@ -156,7 +169,7 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread)
GEN_TEST_FUNCTION(7, 8)
GEN_TEST_FUNCTION(8, 9)
GEN_TEST_FUNCTION(9, 10)
int main(int argc, char *argv[])
{
TestFunc0();
...
...
@@ -165,55 +178,57 @@ You can use DumpCatcher to obtain the call stack of a specified process (thread)
```
## Using ProcessDump to Obtain the Call Stack
## Using DumpCatcher Commands to Obtain Call Stack Information
### Tool Description
ProcessDump is a command line interface (CLI) based tool for capturing call stacks on OpenHarmony. It uses the **-p** and **-t** parameters to specify the process and thread. After the command is executed, the thread stack information of the specified process is displayed in the CLI window.
DumpCatcher Command Tool is a command line interface (CLI)-based tool for capturing call stack information on OpenHarmony. It uses the **-p** and **-t** parameters to specify the process and thread. After the command is executed, the thread stack information of the specified process is displayed in the CLI window. By specifying the **-m** parameter, you can also capture the JS and Native hybrid stack information of an application process.
**Table 3** Usage of the CLI-based ProcessDump
**Table 3** Usage of the DumpCatcher Command Tool
| Tool| Path| Command| Description|
| Tool| Path| Command| Description|
| -------- | -------- | -------- | -------- |
| processdump | /system/bin | - processdump -p [pid]<br>- processdump -p [pid] -t [tid] | **Arguments:**<br>**- -p [pid]**: prints stack information for all threads of the specified process.<br>**- -p [pid] -t [tid]**: prints information for the specified thread of the specified process.<br>**Return value:**<br>If the stack information is parsed successfully, the information is displayed in the standard output. If the stack information fails to be parsed, error information is displayed.|
| dumpcatcher | /system/bin | - dumpcatcher -p [pid]<br>- dumpcatcher -p [pid] -t [tid]<br>- dumpcatcher -m -p [pid]<br>- dumpcatcher -m -p [pid] -t [tid]<br>| **Description:**<br>- **-p [pid]**: prints all thread stack information of the specified process.<br>- **-p [pid] -t [tid]**: prints stack information for the specified thread of the specified process.<br>- **-m -p [pid]**: prints hybrid stack information for all threads of the specified process.<br>- **-m -p [pid] -t [tid]**: prints hybrid stack information for the specified thread of the specified process.<br>**Return value:**<br>If the stack information is parsed successfully, the information is displayed in the standard output. If the stack information fails to be parsed, error information is displayed.|
> This tool must be used by the **root** user, or the caller must have the permission to ptrace the target process and read the smaps of the target process.
### Development Example
### Example
Print call stack information of the **hiview** process.
Use ProcessDump to print the call stack of the **hiview** process.
```
# ps -A | grep hiview
114 ? 00:00:00 hiview
# processdump -p 114 -t 114
Tid:114, Name:hiview
#00 pc 0000000000089824(00000000b6f44824) /system/lib/ld-musl-arm.so.1(ioctl+68)
#01 pc 000000000002a709(00000000b6c56709) /system/lib/libipc_core.z.so(_ZN4OHOS15BinderConnector11WriteBinderEmPv+16)
#02 pc 000000000002ba75(00000000b6c57a75) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker18TransactWithDriverEb+224)
#03 pc 000000000002bb37(00000000b6c57b37) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker13StartWorkLoopEv+22)
#04 pc 000000000002c211(00000000b6c58211) /system/lib/libipc_core.z.so(_ZN4OHOS13BinderInvoker10JoinThreadEb+36)
#05 pc 0000000000038d07(00000000004bcd07) /system/bin/hiview(_ZNSt3__h6vectorINS_9sub_matchINS_11__wrap_iterIPKcEEEENS_9allocatorIS6_EEE8__appendEj+596)
#06 pc 0000000000028655(00000000004ac655) /system/bin/hiview
#07 pc 00000000000c2b08(00000000b6f7db08) /system/lib/ld-musl-arm.so.1(__libc_start_main+116)
#08 pc 00000000000285f4(00000000004ac5f4) /system/bin/hiview
#09 pc 0000000000028580(00000000004ac580) /system/bin/hiview
#00 pc 00098f8c /system/lib/ld-musl-arm.so.1(ioctl+68)
#01 pc 0000e2a1 /system/lib/chipset-pub-sdk/libipc_single.z.so
#02 pc 0000ed59 /system/lib/chipset-pub-sdk/libipc_single.z.so
#03 pc 0000ee1f /system/lib/chipset-pub-sdk/libipc_single.z.so
#04 pc 0000f745 /system/lib/chipset-pub-sdk/libipc_single.z.so
#05 pc 00037577 /system/bin/hiview
#06 pc 00025973 /system/bin/hiview
#07 pc 000db210 /system/lib/ld-musl-arm.so.1
#08 pc 000258d8 /system/bin/hiview
#09 pc 0002587c /system/bin/hiview
```
## Locating Faults Based on Crash Logs
## Locating Faults Based on the Crash Log
You can locate faults based on the crash stack logs generated by FaultLoggerd. This section describes how to use the addr2line tool to locate a crash fault.
You can locate faults based on the crash stack logs generated by Faultloggerd. This section describes how to use the addr2line tool to locate a crash fault.
1. Find a program crash or construct a crash.
For example, insert the following code into your code to trigger an invalid memory access fault (SIGSEGV).
```
NOINLINE int TriggerSegmentFaultException()
{
...
...
@@ -228,40 +243,41 @@ You can locate faults based on the crash stack logs generated by FaultLoggerd. T
2. Obtain the crash function call stack log.
The process generates a temporary log file in the** /data/log/faultlog/temp** directory due to an exception that is not handled. The naming rule of the temporary log file is as follows:
```
cppcrash-pid-time
```
The generated call stack is as follows:
The generated call stack information is as follows:
```
Timestamp:2017-08-05 17:35:03.000
Pid:816
Uid:0
Process name:./crasher
Process name:./crasher_c
Reason:Signal:SIGSEGV(SEGV_ACCERR)@0x0042d33d
Fault thread Info:
Tid:816, Name:crasher
#00 pc 0000332c /data/crasher(TriggerSegmentFaultException+15)(8bc37ceb8d6169e919d178fdc7f5449e)
#01 pc 000035c7 /data/crasher(ParseAndDoCrash+277)(8bc37ceb8d6169e919d178fdc7f5449e)
#02 pc 00003689 /data/crasher(main+39)(8bc37ceb8d6169e919d178fdc7f5449e)
#03 pc 000c3b08 /system/lib/ld-musl-arm.so.1(__libc_start_main+116)
#04 pc 000032f8 /data/crasher(_start_c+112)(8bc37ceb8d6169e919d178fdc7f5449e)
#05 pc 00003284 /data/crasher(_start+32)(8bc37ceb8d6169e919d178fdc7f5449e)
@@ -28,8 +28,7 @@ Constraints on the event domain, event name, and parameter
- Zero or more event names can be defined for one event domain. The event names in the same event domain must be unique.
- Multiple parameters can be defined for one event name. The parameters in the same event name must be unique. There must be only one parameter named **__BASE** in each event name. See Table 1 for the fields of this parameter and Table 2 for the fields of other custom parameters.
- Multiple parameters can be defined for one event name. The parameters in the same event name must be unique. There must be only one parameter named **\__BASE** in each event name. See Table 1 for the fields of this parameter and Table 2 for the fields of other custom parameters.
**Table 1** Fields in the \__BASE parameter
| Field| Description|
...
...
@@ -47,8 +46,10 @@ Constraints on the event domain, event name, and parameter
| arrsize | Length of the parameter of the array type. This field is optional.<br>Value:<br>1-100|
| desc | Parameter description. This field is mandatory.<br>Rule:<br>The description contains 3 to 128 characters, including a to z, A to Z, 0 to 9, and underscores (_).|
HiTraceChain tracks the call chain with the same **traceid** throughout the inter-device, inter-process, and inter-thread service processes. It associates and displays the call relationship and various output information during the entire process, helping you analyze and locate faults and optimize the system.
HiTraceChain tracks the call chain with the same **traceid** throughout the inter-device, inter-process, and inter-thread service processes. It associates and displays the call relationship and various output information during the entire process, helping you analyze and locate faults and optimize the system.
## Use Cases
## When to Use
HiTraceChain can be used for the following purposes:
- Associates and reports service process information \(such as logs and events\) on the device.
- Associates and reports service process information (such as logs and events) on the device.
- Displays and analyzes reported information on the cloud to facilitate fault location.
-Works with the IDE to debug the detailed service process and time consumption distribution for system optimization.
- Works with the IDE to debug the detailed service process and time consumption distribution for system optimization.
1. Display the call relationship in the service process, analyze key paths and function dependency, and determine the time consumption and call frequency at each call point to detect performance bottlenecks.
2. Add **traceid** to logs and events automatically to facilitate comprehensive analysis and quick fault location.
2. Add **traceid** to logs and events automatically to facilitate comprehensive analysis and quick fault location.
## Available APIs
HiTraceChain provides C++ and C APIs. The upper-layer services mainly use HiTraceChain to start and stop call chain tracing.
HiTraceChain provides C++ and C APIs. The upper-layer services mainly use HiTraceChain to start and stop call chain trace.
HiTraceChain is implemented at layer C. It works by transferring **traceid** throughout the service calling process. Before service processing, HiTrace sets **traceid** in the thread local storage (TLS) of the calling thread. During service processing, HiTrace obtains **traceid** from the contextual TLS of the calling thread and automatically adds it to the log and event information. After service processing is complete, HiTrace clears **traceid** from the TLS of the calling thread.
HiTraceChain is implemented at layer C. It works by transferring **traceid** throughout the service calling process. Before service processing, HiTraceChain sets **traceid** in the thread local storage \(TLS\) of the calling thread. During service processing, HiTraceChain obtains **traceid** from the contextual TLS of the calling thread and automatically adds it to the log and event information. After service processing is complete, HiTraceChain clears **traceid** from the TLS of the calling thread.
<tdclass="cellrowborder"valign="top"width="31.430000000000003%"headers="mcps1.2.4.1.2 "><pid="p198391118193717"><aname="p198391118193717"></a><aname="p198391118193717"></a>HiTraceId Begin(const std::string& name, int flags)</p>
</td>
<tdclass="cellrowborder"valign="top"width="58.77%"headers="mcps1.2.4.1.3 "><pid="p684013182375"><aname="p684013182375"></a><aname="p684013182375"></a>Starts HiTraceChain, generates a <strongid="b2063619462230"><aname="b2063619462230"></a><aname="b2063619462230"></a>HiTraceId</strong> object, and sets it in the TLS of the calling thread.</p>
<aname="ul1537854218177"></a><aname="ul1537854218177"></a><ulid="ul1537854218177"><li><strongid="b1566312131676"><aname="b1566312131676"></a><aname="b1566312131676"></a>name</strong>: Indicates the name of the service process.</li><li><strongid="b75512128711"><aname="b75512128711"></a><aname="b75512128711"></a>flags</strong>: Indicates tracing flags, which can be used in combination. <aname="ul18842248101915"></a><aname="ul18842248101915"></a><ulid="ul18842248101915"><li>HITRACE_FLAG_INCLUDE_ASYNC: Traces both synchronous and asynchronous calls. By default, only synchronous calls are traced.</li><li><strongid="b724616241477"><aname="b724616241477"></a><aname="b724616241477"></a>HITRACE_FLAG_DONOT_CREATE_SPAN</strong>: Do not create a span. By default, a span is created.</li><li><strongid="b136181926479"><aname="b136181926479"></a><aname="b136181926479"></a>HITRACE_FLAG_TP_INFO</strong>: Outputs the tracepoint information. By default, the information is not output.</li><li><strongid="b358818291777"><aname="b358818291777"></a><aname="b358818291777"></a>HITRACE_FLAG_NO_BE_INFO</strong>: Do not output the start and end information. By default, the information is output.</li><li><strongid="b38571331974"><aname="b38571331974"></a><aname="b38571331974"></a>HITRACE_FLAG_DONOT_ENABLE_LOG</strong>: Do not associate logs for output. By default, logs are associated for output.</li><li><strongid="b17320371870"><aname="b17320371870"></a><aname="b17320371870"></a>HITRACE_FLAG_FAULT_TRIGGER</strong>: Triggers tracing by fault. By default, tracing is triggered normally.</li><li><strongid="b876915381711"><aname="b876915381711"></a><aname="b876915381711"></a>HITRACE_FLAG_D2D_TP_INFO</strong>: Outputs the device-to-device tracepoint information. By default, the information is not output.</li><li><strongid="b66510421776"><aname="b66510421776"></a><aname="b66510421776"></a>HITRCE_FLAG_DEFAULT</strong>: Indicates the default flag.</li></ul>
</li><li>Output arguments: none</li><li>Return value: Returns a valid <strongid="b7411101522917"><aname="b7411101522917"></a><aname="b7411101522917"></a>HiTraceId</strong> object if call chain tracing is triggered successfully; returns an invalid object otherwise.</li></ul>
<pid="p188401918203713"><aname="p188401918203713"></a><aname="p188401918203713"></a>Note: In nested tracing mode, an invalid object will be returned if tracing is started at the nested layer.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p3840181820372"><aname="p3840181820372"></a><aname="p3840181820372"></a>Stops HiTraceChain based on the <strongid="b1605239122415"><aname="b1605239122415"></a><aname="b1605239122415"></a>HiTraceId</strong> object returned by the <strongid="b7610183992419"><aname="b7610183992419"></a><aname="b7610183992419"></a>Begin</strong> API, and clears the <strongid="b1610173918241"><aname="b1610173918241"></a><aname="b1610173918241"></a>HiTraceId</strong> object in the TLS of the calling thread.</p>
<aname="ul2917140133015"></a><aname="ul2917140133015"></a><ulid="ul2917140133015"><li><strongid="b8201185118711"><aname="b8201185118711"></a><aname="b8201185118711"></a>id</strong>: Indicates the <strongid="b2071183114331"><aname="b2071183114331"></a><aname="b2071183114331"></a>HiTraceId</strong> object.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p98401818123720"><aname="p98401818123720"></a><aname="p98401818123720"></a>Obtains the <strongid="b98371719256"><aname="b98371719256"></a><aname="b98371719256"></a>HiTraceId</strong> object from the TLS of the calling thread.</p>
<pid="p9840418133716"><aname="p9840418133716"></a><aname="p9840418133716"></a>Return value: Returns the <strongid="b73911122162613"><aname="b73911122162613"></a><aname="b73911122162613"></a>HiTraceId</strong> object in the contextual TLS of the calling thread.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p384061893715"><aname="p384061893715"></a><aname="p384061893715"></a>Purpose: Sets the <strongid="b7405852152614"><aname="b7405852152614"></a><aname="b7405852152614"></a>HiTraceId</strong> object in the TLS of the calling thread.</p>
<aname="ul1355016467304"></a><aname="ul1355016467304"></a><ulid="ul1355016467304"><li><strongid="b648307174"><aname="b648307174"></a><aname="b648307174"></a>id</strong>: Indicates the <strongid="b492669584"><aname="b492669584"></a><aname="b492669584"></a>HiTraceId</strong> object.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p584019184379"><aname="p584019184379"></a><aname="p584019184379"></a>Clears the <strongid="b8445182151511"><aname="b8445182151511"></a><aname="b8445182151511"></a>HiTraceId</strong> object in the TLS of the current thread.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p984031812378"><aname="p984031812378"></a><aname="p984031812378"></a>Obtains the span ID from the current <strongid="b186741420142718"><aname="b186741420142718"></a><aname="b186741420142718"></a>HiTraceId</strong> object.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p88419184373"><aname="p88419184373"></a><aname="p88419184373"></a>Outputs HiTraceChain call chain information based on the information type. The information includes the timestamp and <strongid="b185817437323"><aname="b185817437323"></a><aname="b185817437323"></a>HiTraceId</strong> object information of the span.</p>
<aname="ul18619103153812"></a><aname="ul18619103153812"></a><ulid="ul18619103153812"><li><strongid="b7818831083"><aname="b7818831083"></a><aname="b7818831083"></a>type</strong>: Indicates the information type. The options are as follows:<aname="ul1941510328297"></a><aname="ul1941510328297"></a><ulid="ul1941510328297"><li><strongid="b18809161180"><aname="b18809161180"></a><aname="b18809161180"></a>HITRACE_TP_CS</strong>: Client Send, which indicates the messages sent by the synchronous/asynchronous communication client.</li><li><strongid="b327281271319"><aname="b327281271319"></a><aname="b327281271319"></a>HITRACE_TP_SR</strong>: Server Receive, which indicates the messages received by the server in synchronous/asynchronous communication.</li><li><strongid="b10154742682"><aname="b10154742682"></a><aname="b10154742682"></a>HITRACE_TP_SS</strong>: Server Send, which indicates the response messages sent by the server in synchronous communication.</li><li><strongid="b152598127810"><aname="b152598127810"></a><aname="b152598127810"></a>HITRACE_TP_CR</strong>: Client Receive, which indicates the response messages received by the synchronous communication client.</li><li><strongid="b82631512817"><aname="b82631512817"></a><aname="b82631512817"></a>HITRACE_TP_GENERAL</strong>: Indicates the common output information.</li></ul>
</li><li><strongid="b117401716584"><aname="b117401716584"></a><aname="b117401716584"></a>id</strong>: Indicates the ID of the current span.</li><li><strongid="b392172019813"><aname="b392172019813"></a><aname="b392172019813"></a>fmt</strong>: Indicates the string describing the format variable parameter.</li><li><strongid="b986771717818"><aname="b986771717818"></a><aname="b986771717818"></a>args</strong>: Indicates the variable parameter.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p68411618153713"><aname="p68411618153713"></a><aname="p68411618153713"></a>Outputs HiTraceChain call chain information based on the communication mode and information type. The information includes the timestamp and <strongid="b8151210123912"><aname="b8151210123912"></a><aname="b8151210123912"></a>HiTraceId</strong> object information of the span.</p>
<aname="ul914264413811"></a><aname="ul914264413811"></a><ulid="ul914264413811"><li><strongid="b76471824183"><aname="b76471824183"></a><aname="b76471824183"></a>mode</strong>: Indicates the communication mode. The options are as follows:<aname="ul137382469451"></a><aname="ul137382469451"></a><ulid="ul137382469451"><li><strongid="b13732297812"><aname="b13732297812"></a><aname="b13732297812"></a>HITRACE_CM_DEFAULT</strong>: default communication mode used when no communication mode is specified</li><li><strongid="b1820115271789"><aname="b1820115271789"></a><aname="b1820115271789"></a>HITRACE_CM_THREAD</strong>: inter-thread communication</li><li><strongid="b27781831488"><aname="b27781831488"></a><aname="b27781831488"></a>HITRACE_CM_PROCESS</strong>: inter-process communication</li><li><strongid="b15657113313819"><aname="b15657113313819"></a><aname="b15657113313819"></a>HITRACE_CM_DEVICE</strong>: inter-device communication</li></ul>
</li><li><strongid="b172723513812"><aname="b172723513812"></a><aname="b172723513812"></a>type</strong>: Indicates the information type. The options are as follows:<aname="ul19648426458"></a><aname="ul19648426458"></a><ulid="ul19648426458"><li><strongid="b26421037382"><aname="b26421037382"></a><aname="b26421037382"></a>HITRACE_TP_CS</strong>: Client Send, which indicates the messages sent by the synchronous/asynchronous communication client.</li><li><strongid="b66504018818"><aname="b66504018818"></a><aname="b66504018818"></a>HITRACE_TP_SR</strong>: Server Receive, which indicates the messages received by the server in synchronous/asynchronous communication.</li><li><strongid="b285283761"><aname="b285283761"></a><aname="b285283761"></a>HITRACE_TP_SS</strong>: Server Send, which indicates the response messages sent by the server in synchronous communication.</li><li><strongid="b148684447814"><aname="b148684447814"></a><aname="b148684447814"></a>HITRACE_TP_CR</strong>: Client Receive, which indicates the response messages received by the synchronous communication client.</li><li><strongid="b17875164618816"><aname="b17875164618816"></a><aname="b17875164618816"></a>HITRACE_TP_GENERAL</strong>: Indicates the common output information.</li></ul>
</li><li><strongid="b1216749882"><aname="b1216749882"></a><aname="b1216749882"></a>id</strong>: Indicates the ID of the current span.</li><li><strongid="b82757501383"><aname="b82757501383"></a><aname="b82757501383"></a>fmt</strong>: Indicates the string describing the format variable parameter.</li><li><strongid="b15518145114817"><aname="b15518145114817"></a><aname="b15518145114817"></a>args</strong>: Indicates the variable parameter.</li></ul>
<tdclass="cellrowborder"valign="top"width="58.77%"headers="mcps1.2.4.1.3 "><pid="p48419181372"><aname="p48419181372"></a><aname="p48419181372"></a>Represents the default constructor used to generate an invalid <strongid="b1235325844115"><aname="b1235325844115"></a><aname="b1235325844115"></a>HiTraceId</strong> object. </p>
<trid="row138418186374"><tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.1 "><pid="p19841111813712"><aname="p19841111813712"></a><aname="p19841111813712"></a>HiTraceId(const uint8_t* pIdArray, int len)</p>
</td>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p684110183377"><aname="p684110183377"></a><aname="p684110183377"></a>Represents the constructor used to create a <strongid="b1488144194216"><aname="b1488144194216"></a><aname="b1488144194216"></a>HiTraceId</strong> object based on the specified byte array. </p>
<divclass="p"id="p9841151833711"><aname="p9841151833711"></a><aname="p9841151833711"></a>Input arguments:<aname="ul783818256482"></a><aname="ul783818256482"></a><ulid="ul783818256482"><li><strongid="b1725445715818"><aname="b1725445715818"></a><aname="b1725445715818"></a>pIdArray</strong>: Indicates the pointer to a byte array.</li><li><strongid="b3437458486"><aname="b3437458486"></a><aname="b3437458486"></a>len</strong>: Indicates the length of the byte array.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p1084251893713"><aname="p1084251893713"></a><aname="p1084251893713"></a>Checks whether the <strongid="b18546440145116"><aname="b18546440145116"></a><aname="b18546440145116"></a>HiTraceId</strong> object is valid.</p>
<pid="p884261893710"><aname="p884261893710"></a><aname="p884261893710"></a>Return value: Returns <strongid="b20386195514314"><aname="b20386195514314"></a><aname="b20386195514314"></a>true</strong> if the <strongid="b1899544174516"><aname="b1899544174516"></a><aname="b1899544174516"></a>HiTraceId</strong> object is valid; returns <strongid="b1273655294313"><aname="b1273655294313"></a><aname="b1273655294313"></a>false</strong> otherwise.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p128421518153712"><aname="p128421518153712"></a><aname="p128421518153712"></a>Checks whether the tracing flag of the <strongid="b1014619442447"><aname="b1014619442447"></a><aname="b1014619442447"></a>HiTraceId</strong> object is enabled.</p>
<aname="ul9760031103115"></a><aname="ul9760031103115"></a><ulid="ul9760031103115"><li><strongid="b136731441791"><aname="b136731441791"></a><aname="b136731441791"></a>flag</strong>: Indicates the tracing flag. For details, see the description in the <strongid="b186672319452"><aname="b186672319452"></a><aname="b186672319452"></a>Begin</strong> function.</li></ul>
<pid="p98421318143720"><aname="p98421318143720"></a><aname="p98421318143720"></a>Return value: Returns <strongid="b151944819455"><aname="b151944819455"></a><aname="b151944819455"></a>true</strong> if the tracing flag is enabled; returns <strongid="b1619204874513"><aname="b1619204874513"></a><aname="b1619204874513"></a>false</strong> otherwise.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p1084221893717"><aname="p1084221893717"></a><aname="p1084221893717"></a>Enables the tracing flag of the <strongid="b118041135213"><aname="b118041135213"></a><aname="b118041135213"></a>HiTraceId</strong> object.</p>
<aname="ul144862816319"></a><aname="ul144862816319"></a><ulid="ul144862816319"><li><strongid="b430319434"><aname="b430319434"></a><aname="b430319434"></a>flag</strong>: Indicates the tracing flag. For details, see the description in the <strongid="b1067701187"><aname="b1067701187"></a><aname="b1067701187"></a>Begin</strong> function.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p12842151803718"><aname="p12842151803718"></a><aname="p12842151803718"></a>Obtains the tracing flag set in the <strongid="b36515674811"><aname="b36515674811"></a><aname="b36515674811"></a>HiTraceId</strong> object.</p>
<pid="p19842101853716"><aname="p19842101853716"></a><aname="p19842101853716"></a>Return value: Returns the combination of tracing flags. For details, see the description in the <strongid="b12693139144817"><aname="b12693139144817"></a><aname="b12693139144817"></a>Begin</strong> function.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p7842141823718"><aname="p7842141823718"></a><aname="p7842141823718"></a>Sets a tracing flag in the <strongid="b9174314814"><aname="b9174314814"></a><aname="b9174314814"></a>HiTraceId</strong> object.</p>
<aname="ul6490121183115"></a><aname="ul6490121183115"></a><ulid="ul6490121183115"><li><strongid="b1556719154919"><aname="b1556719154919"></a><aname="b1556719154919"></a>flags</strong>: Indicates the combination of tracing flags. For details, see the description in the <strongid="b469312329341"><aname="b469312329341"></a><aname="b469312329341"></a>Begin</strong> function.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p784271815372"><aname="p784271815372"></a><aname="p784271815372"></a>Sets the call chain ID in the <strongid="b1319041125416"><aname="b1319041125416"></a><aname="b1319041125416"></a>HiTraceId</strong> object.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p1484351820374"><aname="p1484351820374"></a><aname="p1484351820374"></a>Obtains the span ID from the current <strongid="b8123101515516"><aname="b8123101515516"></a><aname="b8123101515516"></a>HiTraceId</strong> object.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p14843171816375"><aname="p14843171816375"></a><aname="p14843171816375"></a>Sets the span ID in the <strongid="b13643024185512"><aname="b13643024185512"></a><aname="b13643024185512"></a>HiTraceId</strong> object.</p>
<aname="ul1799516134316"></a><aname="ul1799516134316"></a><ulid="ul1799516134316"><li><strongid="b43891187116"><aname="b43891187116"></a><aname="b43891187116"></a>spanId</strong>: Indicates the span ID.</li></ul>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p884381819373"><aname="p884381819373"></a><aname="p884381819373"></a>Obtains the parent span ID from the current <strongid="b5851839615"><aname="b5851839615"></a><aname="b5851839615"></a>HiTraceId</strong> object.</p>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p1884361803719"><aname="p1884361803719"></a><aname="p1884361803719"></a>Sets the parent span ID in the <strongid="b1660960324"><aname="b1660960324"></a><aname="b1660960324"></a>HiTraceId</strong> object.</p>
<trid="row128435182379"><tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.1 "><pid="p5843181816371"><aname="p5843181816371"></a><aname="p5843181816371"></a>int ToBytes(uint8_t* pIdArray, int len)</p>
</td>
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p8843171818378"><aname="p8843171818378"></a><aname="p8843171818378"></a>Converts the <strongid="b68851225439"><aname="b68851225439"></a><aname="b68851225439"></a>HiTraceId</strong> object into a byte array to facilitate caching or communication transfer.</p>
<aname="ul169461002314"></a><aname="ul169461002314"></a><ulid="ul169461002314"><li><strongid="b960934311010"><aname="b960934311010"></a><aname="b960934311010"></a>pIdArray</strong>: Indicates the pointer to a byte array. The minimum length of the byte array is <strongid="b96124430106"><aname="b96124430106"></a><aname="b96124430106"></a>HITRACE_ID_LEN</strong>.</li><li><strongid="b13672164941019"><aname="b13672164941019"></a><aname="b13672164941019"></a>len</strong>: Indicates the length of the byte array.</li></ul>
<aname="ul116274319312"></a><aname="ul116274319312"></a><ulid="ul116274319312"><li><strongid="b12376938695"><aname="b12376938695"></a><aname="b12376938695"></a>pIdArray</strong>: Indicates the pointer to a byte array. If the object is valid, the object data after conversion is stored.</li></ul>
<pid="p8843618143720"><aname="p8843618143720"></a><aname="p8843618143720"></a>Return value: Returns a value greater than 0 (indicating a valid array of object data) if the conversion is successful; returns <strongid="b2156170234"><aname="b2156170234"></a><aname="b2156170234"></a>0</strong> otherwise.</p>
</td>
</tr>
</tbody>
</table>
## Call Chain Processing
Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. **HiTraceChain** requires transfer of **traceid** in the communication mechanism.
Some built-in communication mechanisms \(such as ZIDL\) of OpenHarmony already support the transfer of **traceid**.
The following figure shows the process of transferring **traceid** in synchronous call. The process of transferring **traceid** in asynchronous call is similar.
Extended communication mechanisms can also follow this implementation.
**Figure 5** Call chain tracing in synchronous communication
| HITRACE_FLAG_INCLUDE_ASYNC | 1 | Asynchronous call flag. By default, only synchronous calls are traced. If this flag is set, both synchronous and asynchronous calls will be traced. |
| HITRACE_FLAG_DONOT_CREATE_SPAN | 1 << 1 | No span flag. By default, spans are created within a trace of synchronous and asynchronous service calls. If this flag is set, no spans are created. |
| HITRACE_FLAG_TP_INFO | 1 << 2 | Trace point flag. By default, no trace point is added when trace is enabled. This flag is used for debugging. If this flag is set, trace points will be automatically added on the TX and RX sides of synchronous and asynchronous calls to output trace point and timestamp information. Trace points are classified into four types: client send (CS), server receive (SR), server send (SS), and client receive (CR). For a synchronous call, the output trace points are CS, SR, SS, and CR; for an asynchronous call, the output trace points are CS, SR, and SS. |
| HITRACE_FLAG_NO_BE_INFO | 1 << 3 | No begin/end flag. By default, information about the start and end of the trace task is printed. If this flag is set, information about the start and end of the trace task will not be printed.|
| HITRACE_FLAG_DONOT_ENABLE_LOG | 1 << 4 | Log association flag. If this flag is set, information about the trace task will not be printed. |
| HITRACE_FLAG_FAULT_TRIGGER | 1 << 5 | Failure trigger flag. This flag is reserved for future use. |
| HITRACE_FLAG_D2D_TP_INFO | 1 << 6 | Device-to-device trace point flag. It is a subset of **TP_INFO**. If this flag is set, trace points are added only for call chain trace between devices.|
**Table 3** Trace point types
| **Name**| **Value**| **Description**|
| -------- | -------- | -------- |
| HITRACE_TP_CS | 0 | CS trace point. |
| HITRACE_TP_CR | 1 | CR trace point. |
| HITRACE_TP_SS | 2 | SS trace point. |
| HITRACE_TP_SR | 3 | SR trace point. |
| HITRACE_TP_GENERAL | 4 | General trace points except CS, CR, SS, and SR.|
**Table 4** Communication modes
| **Name**| **Value**| **Description**|
| -------- | -------- | -------- |
| HITRACE_CM_DEFAULT | 0 | Default communication mode. |
| HiTraceChain | HiTraceId Begin(const std::string& name, int flags) | Starts HiTraceChain, generates a **HiTraceId** object, and sets it in the TLS of the calling thread.<br>Input arguments:<br>- **name**: name of the service process.<br>- **flags**: trace flags, which can be used in combination. For details, see Table 2.<br>Output arguments: none<br>Return value: a valid **HiTraceId** object if call chain trace is triggered successfully; returns an invalid object otherwise.<br>Note: In nested trace mode, an invalid object will be returned if trace is started at the nested layer.|
| | void End(const HiTraceId& id) | Stops HiTraceChain based on the **HiTraceId** object returned by the **Begin** API, and clears the **HiTraceId** object in the TLS of the calling thread.<br>Input arguments:<br>- **id**: **HiTraceId** object.<br>Output arguments: none<br>Return value: none|
| | HiTraceId GetId(); | Obtains the **HiTraceId** object from the TLS of the calling thread.<br>Input arguments: none<br>Output arguments: none<br>Return value: **HiTraceId** object in the contextual TLS of the calling thread.|
| | void SetId(const HiTraceId& id) | Purpose: Sets the **HiTraceId** object in the TLS of the calling thread.<br>Input arguments:<br>- **id**: **HiTraceId** object.<br>Output arguments: none<br>Return value: none|
| | void ClearId() | Clears the **HiTraceId** object in the TLS of the calling thread.<br>Input arguments: none<br>Output arguments: none<br>Return value: none|
| | HiTraceId CreateSpan() | Obtains the span ID from the current **HiTraceId** object.<br>Input arguments: none<br>Output arguments: none<br>Return value: current span ID.|
| | void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | Outputs HiTraceChain trace point information based on the information type. The information includes the timestamp and **HiTraceId** object of the span.<br>Input arguments:<br>- **type**: trace point type. For details, see Table 3.<br>- **id**: ID of the current span.<br>- **fmt**: string describing the format variable parameter.<br>- **args**: variable parameter.<br>Output arguments: none<br>Return value: none|
| | void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...) | Outputs HiTraceChain trace point information based on the communication mode and information type. The information includes the timestamp and **HiTraceId** object of the span.<br>Input arguments:<br>- **mode**: communication mode. For details, see Table 4.<br>- **type**: trace point type. For details, see Table 3.<br>- **id**: ID of the current span.<br>- **fmt**: string describing the format variable parameter.<br>- **args**: variable parameter.<br>Output arguments: none<br>Return value: none|
| HiTraceId | HiTraceId(); | Represents the default constructor used to generate an invalid **HiTraceId** object. <br>Input arguments: none<br>Output arguments: none<br>Return value: none|
| | HiTraceId(const uint8_t* pIdArray, int len) | Represents the constructor used to create a **HiTraceId** object based on the specified byte array. <br>Input arguments:<br>- **pIdArray**: pointer to a byte array.<br>- **len**: length of the byte array.<br>Output arguments: none<br>Return value: none|
| | bool IsValid() | Checks whether the **HiTraceId** object is valid.<br>Input arguments: none<br>Output arguments: none<br>Return value: **true** if the **HiTraceId** object is valid; **false** otherwise.|
| | bool IsFlagEnabled(HiTraceFlag flag) | Checks whether the trace flag of the **HiTraceId** object is enabled.<br>Input arguments:<br>- **flag**: trace flag. For details, see the description in the **Begin** function.<br>Output arguments: none<br>Return value: **true** if the trace flag is enabled; **false** otherwise.|
| | void EnableFlag(HiTraceFlag flag) | Enables the trace flag of the **HiTraceId** object.<br>Input arguments:<br>- **flag**: trace flag. For details, see the description in the **Begin** function.<br>Output arguments: none<br>Return value: none|
| | int GetFlags() | Obtains the trace flag set in the **HiTraceId** object.<br>Input arguments: none<br>Output arguments: none<br>Return value: Returns the combination of trace flags. For details, see the description in the **Begin** function.|
| | void SetFlags(int flags) | Sets a trace flag in the **HiTraceId** object.<br>Input arguments:<br>- **flags**: combination of trace flags. For details, see the description in the **Begin** function.<br>Output arguments: none<br>Return value: none|
| | void SetChainId(uint64_t chainId) | Sets the call chain ID in the **HiTraceId** object.<br>Input arguments:<br>- **chainId**: call chain ID.<br>Output arguments: none<br>Return value: none|
| | uint64_t GetSpanId() | Obtains the span ID from the current **HiTraceId** object.<br>Input arguments: none<br>Output arguments: none<br>Return value: current span ID.|
| | void SetSpanId(uint64_t spanId) | Sets the span ID in the **HiTraceId** object.<br>Input arguments:<br>- **spanId**: span ID.<br>Output arguments: none<br>Return value: none|
| | uint64_t GetParentSpanId() | Obtains the parent span ID from the current **HiTraceId** object.<br>Input arguments: none<br>Output arguments: none<br>Return value: parent span ID.|
| | void SetParentSpanId(uint64_t parentSpanId) | Sets the parent span ID in the **HiTraceId** object.<br>Input arguments:<br>- **parentSpanId**: parent span ID.<br>Output arguments: none<br>Return value: none|
| | int ToBytes(uint8_t* pIdArray, int len) | Converts the **HiTraceId** object into a byte array to facilitate caching or communication transfer.<br>Input arguments:<br>- **pIdArray**: pointer to a byte array. The minimum length of the byte array is **HITRACE_ID_LEN**.<br>- **len**: length of the byte array.<br>Output parameters:<br>- **pIdArray**: pointer to a byte array. If the object is valid, the object data after conversion is stored.<br>Return value: a value greater than **0** (indicating a valid array of object data) if the conversion is successful; **0** otherwise.|
### Call Chain Processing
Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. HiTraceChain requires transfer of **traceid** in the communication mechanism.
Some built-in communication mechanisms (such as ZIDL) of OpenHarmony already support the transfer of **traceid**.
The following figure shows the process of transferring **traceid** in synchronous call. The process of transferring **traceid** in asynchronous call is similar.
Extended communication mechanisms can also follow this implementation.
**Figure 5** Call chain trace in synchronous communication
1. The service module on the client calls the **begin\(\)** function to start call chain tracing.
2. The service module on the client synchronously calls the **transact** function to the communication component on the client.
3. The communication component on the client performs the following:
1. Obtains **traceid** from the TLS of the calling thread.
2. Generates child **traceid**.
3. Writes child **traceid** into the transaction data \(synchronous communication data\).
4. Performs Client Send \(CS\) tracing.
5. Sends communication data to the communication component on the server.
4. On receiving the communication data, the communication component on the server performs the following:
1. Obtains **traceid** from the data message package.
2. Sets **traceid** in the TLS of the calling thread.
3. Performs Server Receive \(SR\) tracing.
4. Synchronously call the **onTransact** callback to the service module on the server.
5. The service module on the server processes the service and sends the transact reply message carrying the processing result to the communication component.
6. The communication component on the server performs the following:
1. Performs Server Send \(SS\) tracing.
2. Sends communication data to the communication component on the client.
3. Clears **traceid** from the TLS of the calling thread.
7. On receiving the communication data, the communication component on the client performs the following:
1. Performs Client Receive \(CR\) tracing.
2. Sends a transact reply response to the service module on the client.
8. The service module on the client processes the transact reply response.
9. When the process ends, the service module on the client calls the **end\(\)** function to stop call chain tracing.
## How to Develop
### C++
1. Develop the source code.
1. The service module on the client calls the **begin()** function to start call chain trace.
Include the **hitracechain** header file in the class definition header file or class implementation source file. For example:
2. The service module on the client synchronously calls the **transact** function to the communication component on the client.
```
#include "hitrace/tracechain.h"
```
3. The communication component on the client performs the following:
1. Obtains **traceid** from the TLS of the calling thread.
2. Generates child **traceid**.
3. Writes child **traceid** into the transaction data (synchronous communication data).
4. Performs CS trace.
5. Sends communication data to the communication component on the server.
Add the code to start and stop call chain tracing in the class implementation source file.
4. On receiving the communication data, the communication component on the server performs the following:
1. Obtains **traceid** from the data message package.
2. Sets **traceid** in the TLS of the calling thread.
3. Performs SR trace.
4. Synchronously calls the **onTransact** callback to the service module on the server.
```
using namespace OHOS::HiviewDFX;
auto traceId = HiTraceChain::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT);
...
HiTraceChain::End(traceId);
```
5. The service module on the server processes the service and sends the transact reply message carrying the processing result to the communication component.
2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**.
6. The communication component on the server performs the following:
1. Performs SS trace.
2. Sends communication data to the communication component on the client.
3. Clears **traceid** from the TLS of the calling thread.
```
external_deps = [ "hiviewdfx:libhitracechain" ]
```
7. On receiving the communication data, the communication component on the client performs the following:
1. Performs CR trace.
2. Sends a transact reply response to the service module on the client.
8. The service module on the client processes the transact reply response.
### C
9. When the process ends, the service module on the client calls the **end()** function to stop call chain trace.
1. Develop the source code.
Include the **hitracechain** header file in the source file.
```
#include "hitrace/tracechain.h"
```
Add the code to start and stop call chain tracing in the class implementation source file.
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
...
...
@@ -12,7 +12,7 @@ The HiTraceMeter subsystem consists of three parts:
- hitrace CLI tool for data collection
- 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.
...
...
@@ -348,4 +348,4 @@ You can set **-t** to **60** and **-b** to **204800** to increase the trace time
# Reference
For details about HiTraceMeter, see [hiviewdfx_hitrace: 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\).
## Introduction
[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:
- 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\).
- HiTraceChain: implements distributed call chain tracing. It is applicable to standard-system devices \(reference memory ≥ 128 MiB\).
- 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 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\).
- 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\).
- 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\).
- 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.
**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**
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.
