README.md
1# HiTrace<a name="EN-US_TOPIC_0000001078081802"></a>
2
3- [Overview](#section11660541593)
4- [Architecture](#section16334748141112)
5- [Directory Structure](#section161941989596)
6- [Constraints](#section119744591305)
7- [Usage](#section1312121216216)
8 - [Available APIs](#section1551164914237)
9 - [Usage Guidelines](#section129654513264)
10
11- [Repositories Involved](#section1371113476317)
12
13## Overview<a name="section11660541593"></a>
14
15HiTrace provides APIs to implement call chain tracing throughout a service process. With HiTrace, you can quickly obtain the run log for the call chain of a specified service process and locate faults in cross-device, cross-process, or cross-thread communications.
16
17## Architecture<a name="section16334748141112"></a>
18
19**Figure 1** Architecture of HiTrace <a name="fig4460722185514"></a>
20
21
22
23
24HiTrace is the lightweight implementation based on the distributed call chain of cloud computing. HiTrace implements call chain tracing as follows:
25
26- Transfers **traceid** in cross-device, cross-process, and cross-thread communications.
27- Stores **traceid** in the thread local storage \(TLS\) at the Native layer of the process.
28- Automatically adds **traceid** to existing events and run logs.
29
30## Directory Structure<a name="section161941989596"></a>
31
32```
33/base/hiviewdfx/hitrace
34├── frameworks # Framework code
35│ └── native # HiTrace Native implementation code
36├── interfaces # APIs
37│ └── js # JS APIs
38│ └── kits # JS inner implementation code
39│ └── native # C/C++ APIs
40│ └── innerkits # Header files opened to internal subsystems
41└── test # Test cases
42```
43
44## Constraints<a name="section119744591305"></a>
45
46HiTrace is already supported by the IPC and EventHandler communication mechanisms. If you are using a custom communication mechanism, adaptation is required to use HiTrace.
47
48## Usage<a name="section1312121216216"></a>
49
50### Available APIs<a name="section1551164914237"></a>
51
52Major APIs of HiTrace
53
54<a name="table1764215412123"></a>
55
56<table><tbody><tr id="row1370464111219"><td class="cellrowborder" valign="top" width="8.98%"><p id="p1670474115124"><a name="p1670474115124"></a><a name="p1670474115124"></a><strong id="b13126192811515"><a name="b13126192811515"></a><a name="b13126192811515"></a>Class</strong></p>
57</td>
58<td class="cellrowborder" valign="top" width="27.47%"><p id="p167041041191214"><a name="p167041041191214"></a><a name="p167041041191214"></a><strong id="b93135237153"><a name="b93135237153"></a><a name="b93135237153"></a>API</strong></p>
59</td>
60<td class="cellrowborder" valign="top" width="63.55%"><p id="p970484112122"><a name="p970484112122"></a><a name="p970484112122"></a><strong id="b4370358151913"><a name="b4370358151913"></a><a name="b4370358151913"></a>Description</strong></p>
61</td>
62</tr>
63<tr id="row970417418126"><td class="cellrowborder" rowspan="2" valign="top" width="8.98%"><p id="p16704184111220"><a name="p16704184111220"></a><a name="p16704184111220"></a>HiTrace</p>
64</td>
65<td class="cellrowborder" valign="top" width="27.47%"><p id="p1270444181220"><a name="p1270444181220"></a><a name="p1270444181220"></a>HiTraceId begin(String name, int flags)</p>
66</td>
67<td class="cellrowborder" valign="top" width="63.55%"><p id="p20704144114123"><a name="p20704144114123"></a><a name="p20704144114123"></a>Starts call chain tracing, generates a <strong id="b52151451154412"><a name="b52151451154412"></a><a name="b52151451154412"></a>HiTraceId</strong> object, and sets it in the TLS of the calling thread.</p>
68<p id="p1270494114128"><a name="p1270494114128"></a><a name="p1270494114128"></a>Input parameters:</p>
69<p id="p370434151220"><a name="p370434151220"></a><a name="p370434151220"></a><strong id="b1586330121717"><a name="b1586330121717"></a><a name="b1586330121717"></a>name</strong>: Indicates the name of the service process.</p>
70<p id="p9704104181212"><a name="p9704104181212"></a><a name="p9704104181212"></a><strong id="b10973143151713"><a name="b10973143151713"></a><a name="b10973143151713"></a>flags</strong>: Indicates call chain flags, which can be used in combination. </p>
71<p id="p187046416125"><a name="p187046416125"></a><a name="p187046416125"></a><strong id="b3332144316176"><a name="b3332144316176"></a><a name="b3332144316176"></a>HITRACE_FLAG_INCLUDE_ASYNC</strong>: Traces both synchronous and asynchronous calls. By default, only synchronous calls are traced.</p>
72<p id="p12704104121212"><a name="p12704104121212"></a><a name="p12704104121212"></a><strong id="b17906163911715"><a name="b17906163911715"></a><a name="b17906163911715"></a>HITRACE_FLAG_DONOT_CREATE_SPAN</strong>: Do note create a span. By default, a span is created.</p>
73<p id="p17704104171210"><a name="p17704104171210"></a><a name="p17704104171210"></a><strong id="b16819174510193"><a name="b16819174510193"></a><a name="b16819174510193"></a>HITRACE_FLAG_TP_INFO</strong>: Outputs the tracepoint information. By default, the tracepoint information is not output.</p>
74<p id="p97041241181215"><a name="p97041241181215"></a><a name="p97041241181215"></a><strong id="b15542450201714"><a name="b15542450201714"></a><a name="b15542450201714"></a>HITRACE_FLAG_NO_BE_INFO</strong>: Do not output the start and end information. By default, the information is output.</p>
75<p id="p47041241151211"><a name="p47041241151211"></a><a name="p47041241151211"></a><strong id="b68075771720"><a name="b68075771720"></a><a name="b68075771720"></a>HITRACE_FLAG_DONOT_ENABLE_LOG</strong>: Do not associate logs for output. By default, logs are associated for output.</p>
76<p id="p147041741141215"><a name="p147041741141215"></a><a name="p147041741141215"></a><strong id="b11871181131812"><a name="b11871181131812"></a><a name="b11871181131812"></a>HITRACE_FLAG_FAULT_TRIGGER</strong>: Triggers call chain tracing by fault. By default, call chain tracing is triggered normally.</p>
77<p id="p2704164181214"><a name="p2704164181214"></a><a name="p2704164181214"></a><strong id="b59161113131816"><a name="b59161113131816"></a><a name="b59161113131816"></a>HITRACE_FLAG_D2D_TP_INFO</strong>: Outputs inter-device tracepoint information. By default, the tracepoint information is not output.</p>
78<p id="p17704941121210"><a name="p17704941121210"></a><a name="p17704941121210"></a><strong id="b20659623501"><a name="b20659623501"></a><a name="b20659623501"></a>HITRACE_FLAG_DEFAULT</strong>: Indicates the default flag.</p>
79<p id="p17704174141216"><a name="p17704174141216"></a><a name="p17704174141216"></a>Output parameters: none</p>
80<p id="p07045418125"><a name="p07045418125"></a><a name="p07045418125"></a>Return value: Returns a valid <strong id="b149053347524"><a name="b149053347524"></a><a name="b149053347524"></a>HiTraceId</strong> object if call chain tracing is triggered successfully; returns an invalid object otherwise.</p>
81<p id="p17041941151217"><a name="p17041941151217"></a><a name="p17041941151217"></a>Note: In nested tracing mode, an invalid object will be returned if tracing is started at the nested layer.</p>
82</td>
83</tr>
84<tr id="row18704194111211"><td class="cellrowborder" valign="top"><p id="p11704641131213"><a name="p11704641131213"></a><a name="p11704641131213"></a>void end(HiTraceId id)</p>
85</td>
86<td class="cellrowborder" valign="top"><p id="p20704144141212"><a name="p20704144141212"></a><a name="p20704144141212"></a>Stops call chain tracing based on the <strong id="b109681242310"><a name="b109681242310"></a><a name="b109681242310"></a>HiTraceId</strong> object returned by the <strong id="b171995411436"><a name="b171995411436"></a><a name="b171995411436"></a>Begin</strong> API, and clears the <strong id="b87181818247"><a name="b87181818247"></a><a name="b87181818247"></a>HiTraceId</strong> object in the TLS of the calling thread.</p>
87<p id="p7704174181215"><a name="p7704174181215"></a><a name="p7704174181215"></a>Input parameters:</p>
88<p id="p14704134111216"><a name="p14704134111216"></a><a name="p14704134111216"></a><strong id="b15542231182"><a name="b15542231182"></a><a name="b15542231182"></a>id</strong>: Indicates the <strong id="b046517501252"><a name="b046517501252"></a><a name="b046517501252"></a>HiTraceId</strong> object.</p>
89<p id="p15704104111215"><a name="p15704104111215"></a><a name="p15704104111215"></a>Output parameters: none</p>
90<p id="p16704741181213"><a name="p16704741181213"></a><a name="p16704741181213"></a>Return value: none</p>
91</td>
92</tr>
93</tbody>
94</table>
95
96
97## Repositories Involved<a name="section1371113476317"></a>
98
99[DFX SubSystem](https://gitee.com/openharmony/docs/blob/master/en/readme/dfx.md)
100
101[hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README.md)
102
103[hiviewdfx\_hilog](https://gitee.com/openharmony/hiviewdfx_hilog/blob/master/README.md)
104
105[hiviewdfx\_hiappevent](https://gitee.com/openharmony/hiviewdfx_hiappevent/blob/master/README.md)
106
107[hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README.md)
108
109
README_zh.md
1# HiTrace组件<a name="ZH-CN_TOPIC_0000001078081802"></a>
2
3- [简介](#section11660541593)
4- [组件框架](#section16334748141112)
5- [目录](#section161941989596)
6- [约束](#section119744591305)
7- [说明](#section1312121216216)
8 - [接口说明](#section1551164914237)
9 - [使用说明](#section129654513264)
10
11- [相关仓](#section1371113476317)
12
13## 简介<a name="section11660541593"></a>
14
15HiTrace在OpenHarmony中，为开发者提供业务流程调用链跟踪的维测接口。通过使用该接口所提供的功能，可以帮助开发者迅速获取指定业务流程调用链的运行日志、定位跨设备/跨进程/跨线程的故障问题。
16
17## 组件框架<a name="section16334748141112"></a>
18
19**图 1** 组件框架图<a name="fig4460722185514"></a>
20
21
22
23
24HiTrace实现机制：
25
26- 基于云计算分布式调用链思想的轻量级实现。
27- 在跨设备/跨进程/跨线程的通信机制中传递traceid。
28- 在进程Native层TLS（Thread Local Storage）中存储traceid。
29- 在事件、运行日志中自动附加traceid。
30
31## 目录<a name="section161941989596"></a>
32
33```
34/base/hiviewdfx/hitrace
35├── frameworks # 框架代码
36│ └── native # HiTrace native实现代码
37├── interfaces # 接口
38│ └── js # js接口
39│ └── kits # js接口内部实现代码
40│ └── native # C/C++接口
41│ └── innerkits # 对内部子系统暴露的头文件
42└── test # 测试用例代码
43```
44
45## 约束<a name="section119744591305"></a>
46
47系统通用的通信机制\(IPC, EventHandler\)已支持HiTrace机制， 对业务自定义通信机制需要适配HiTrace机制。
48
49## 说明<a name="section1312121216216"></a>
50
51### 接口说明<a name="section1551164914237"></a>
52
53C++主要接口：
54
55<a name="table1764215412123"></a>
56<table><tbody><tr id="row1370464111219"><td class="cellrowborder" valign="top" width="8.98%"><p id="p1670474115124"><a name="p1670474115124"></a><a name="p1670474115124"></a><strong id="b1970404151213"><a name="b1970404151213"></a><a name="b1970404151213"></a>类</strong></p>
57</td>
58<td class="cellrowborder" valign="top" width="27.47%"><p id="p167041041191214"><a name="p167041041191214"></a><a name="p167041041191214"></a><strong id="b5925204893112"><a name="b5925204893112"></a><a name="b5925204893112"></a>方法</strong></p>
59</td>
60<td class="cellrowborder" valign="top" width="63.55%"><p id="p970484112122"><a name="p970484112122"></a><a name="p970484112122"></a><strong id="b2926194820311"><a name="b2926194820311"></a><a name="b2926194820311"></a>描述</strong></p>
61</td>
62</tr>
63<tr id="row970417418126"><td class="cellrowborder" rowspan="2" valign="top" width="8.98%"><p id="p16704184111220"><a name="p16704184111220"></a><a name="p16704184111220"></a>HiTrace</p>
64</td>
65<td class="cellrowborder" valign="top" width="27.47%"><p id="p1270444181220"><a name="p1270444181220"></a><a name="p1270444181220"></a>HiTraceId begin(String name, int flags)</p>
66</td>
67<td class="cellrowborder" valign="top" width="63.55%"><p id="p20704144114123"><a name="p20704144114123"></a><a name="p20704144114123"></a>功能：启动Hitrace跟踪，生成HiTraceId对象并设置到当前线程TLS中。</p>
68<p id="p1270494114128"><a name="p1270494114128"></a><a name="p1270494114128"></a>输入参数：</p>
69<p id="p370434151220"><a name="p370434151220"></a><a name="p370434151220"></a>name：业务流程名称。</p>
70<p id="p9704104181212"><a name="p9704104181212"></a><a name="p9704104181212"></a>flags：跟踪指示位，可以组合使用，具体含义为：</p>
71<p id="p187046416125"><a name="p187046416125"></a><a name="p187046416125"></a>HITRACE_FLAG_INCLUDE_ASYNC：同时跟踪同步调用和异步调用，缺省只跟踪同步调用。</p>
72<p id="p12704104121212"><a name="p12704104121212"></a><a name="p12704104121212"></a>HITRACE_FLAG_DONOT_CREATE_SPAN：不创建子分支，缺省创建子分支。</p>
73<p id="p17704104171210"><a name="p17704104171210"></a><a name="p17704104171210"></a>HITRACE_FLAG_TP_INFO：输出tracepoint信息，缺省不输出。</p>
74<p id="p97041241181215"><a name="p97041241181215"></a><a name="p97041241181215"></a>HITRACE_FLAG_NO_BE_INFO：不输出起始、结束信息，缺省输出。</p>
75<p id="p47041241151211"><a name="p47041241151211"></a><a name="p47041241151211"></a>HITRACE_FLAG_DONOT_ENABLE_LOG：不与日志关联输出，缺省关联。</p>
76<p id="p147041741141215"><a name="p147041741141215"></a><a name="p147041741141215"></a>HITRACE_FLAG_FAULT_TRIGGER：故障触发的跟踪，缺省为正常启动的。</p>
77<p id="p2704164181214"><a name="p2704164181214"></a><a name="p2704164181214"></a>HITRACE_FLAG_D2D_TP_INFO：输出设备间tracepoint信息，缺省不输出。</p>
78<p id="p17704941121210"><a name="p17704941121210"></a><a name="p17704941121210"></a>HITRACE_FLAG_DEFAULT: 缺省标志。</p>
79<p id="p17704174141216"><a name="p17704174141216"></a><a name="p17704174141216"></a>输出参数：无</p>
80<p id="p07045418125"><a name="p07045418125"></a><a name="p07045418125"></a>返回值：启动跟踪超过返回有效HiTraceId对象，否则返回无效对象。</p>
81<p id="p17041941151217"><a name="p17041941151217"></a><a name="p17041941151217"></a>注意：嵌套启动跟踪时，内层启动调用返回无效对象。</p>
82</td>
83</tr>
84<tr id="row18704194111211"><td class="cellrowborder" valign="top"><p id="p11704641131213"><a name="p11704641131213"></a><a name="p11704641131213"></a>void end(HiTraceId id)</p>
85</td>
86<td class="cellrowborder" valign="top"><p id="p20704144141212"><a name="p20704144141212"></a><a name="p20704144141212"></a>功能：根据begin返回的HiTraceId停止HiTrace跟踪；清除当前线程TLS中HiTraceId内容。</p>
87<p id="p7704174181215"><a name="p7704174181215"></a><a name="p7704174181215"></a>输入参数：</p>
88<p id="p14704134111216"><a name="p14704134111216"></a><a name="p14704134111216"></a>id：HiTraceId对象</p>
89<p id="p15704104111215"><a name="p15704104111215"></a><a name="p15704104111215"></a>输出参数：无</p>
90<p id="p16704741181213"><a name="p16704741181213"></a><a name="p16704741181213"></a>返回值：无</p>
91</td>
92</tr>
93</tbody>
94</table>
95
96
97## 相关仓<a name="section1371113476317"></a>
98
99[DFX子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/DFX%E5%AD%90%E7%B3%BB%E7%BB%9F.md)
100
101[hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README_zh.md)
102
103[hiviewdfx\_hilog](https://gitee.com/openharmony/hiviewdfx_hilog/blob/master/README_zh.md)
104
105[hiviewdfx\_hiappevent](https://gitee.com/openharmony/hiviewdfx_hiappevent/blob/master/README_zh.md)
106
107[hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README_zh.md)
108
