HiTrace 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<a name="section134561822574"></a>
HiTrace can be used for the following purposes:
HiTraceChain can be used for the following purposes:
- 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.
- 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.
**Figure 1** Use cases of HiTrace<a name="fig179241023125715"></a>
**Figure 1** Use cases of HiTraceChain<a name="fig179241023125715"></a>
@@ -33,9 +35,9 @@ HiTrace can be used for the following purposes:
## Available APIs<a name="section1517945334617"></a>
HiTrace provides C++ and C APIs. The upper-layer services mainly use HiTrace 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 tracing.
HiTrace 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.
### Java, C++, and C APIs<a name="section932504474"></a>
...
...
@@ -56,7 +58,7 @@ HiTrace is implemented at layer C. It works by transferring **traceid** throug
@@ -217,7 +219,7 @@ HiTrace is implemented at layer C. It works by transferring **traceid** throug
</td>
<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 HiTrace, generates a <strongid="b2063619462230"><aname="b2063619462230"></a><aname="b2063619462230"></a>HiTraceId</strong> object, and sets it in the TLS of the calling thread.</p>
<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>
...
...
@@ -226,7 +228,7 @@ HiTrace is implemented at layer C. It works by transferring **traceid** throug
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p3840181820372"><aname="p3840181820372"></a><aname="p3840181820372"></a>Stops HiTrace 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>
<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="p88419184373"><aname="p88419184373"></a><aname="p88419184373"></a>Outputs HiTrace 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>
<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>
...
...
@@ -278,7 +280,7 @@ HiTrace is implemented at layer C. It works by transferring **traceid** throug
<tdclass="cellrowborder"valign="top"headers="mcps1.2.4.1.2 "><pid="p68411618153713"><aname="p68411618153713"></a><aname="p68411618153713"></a>Outputs HiTrace 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>
<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>
...
...
@@ -428,7 +430,7 @@ HiTrace is implemented at layer C. It works by transferring **traceid** throug
Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. **HiTrace** requires transfer of **traceid** in the communication mechanism.
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**.
...
...
@@ -475,25 +477,25 @@ The process is as follows:
1. Develop the source code.
Include the **hitrace** header file in the class definition header file or class implementation source file. For example:
Include the **hitracechain** header file in the class definition header file or class implementation source file. For example:
```
#include "hitrace/trace.h"
#include "hitrace/tracechain.h"
```
Add the code to start and stop call chain tracing in the class implementation source file.
HiTrace实现在C层，主要原理是在一次业务调用流程中，利用通信传递traceid，在业务处理前将traceid设置到当前线程的TLS(Thread Local Storage)中，业务处理结束清除当前线程的TLS；这样的话，在业务处理中可以从当前线程的上下文TLS取到traceid，自动附加到日志、事件信息中。
HiTraceChain实现在C层，主要原理是在一次业务调用流程中，利用通信传递traceid，在业务处理前将traceid设置到当前线程的TLS(Thread Local Storage)中，业务处理结束清除当前线程的TLS；这样的话，在业务处理中可以从当前线程的上下文TLS取到traceid，自动附加到日志、事件信息中。
