README.md · Federer-JC/hiviewdfx_hitrace_1108

# HiTrace<a name="EN-US_TOPIC_0000001078081802"></a>

-   [Overview](#section11660541593)
-   [Architecture](#section16334748141112)
-   [Directory Structure](#section161941989596)
-   [Constraints](#section119744591305)
-   [Usage](#section1312121216216)
    -   [Available APIs](#section1551164914237)
    -   [Usage Guidelines](#section129654513264)

-   [Repositories Involved](#section1371113476317)

## Overview<a name="section11660541593"></a>

HiTrace 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.

## Architecture<a name="section16334748141112"></a>

**Figure 1** Architecture of HiTrace <a name="fig4460722185514"></a>

![](figures/en-us_image_0000001123644797.png)

HiTrace is the lightweight implementation based on the distributed call chain of cloud computing. HiTrace implements call chain tracing as follows:

-   Transfers  **traceid**  in cross-device, cross-process, and cross-thread communications.
-   Stores  **traceid**  in the thread local storage \(TLS\) at the Native layer of the process.
-   Automatically adds  **traceid**  to existing events and run logs.

## Directory Structure<a name="section161941989596"></a>

```
/base/hiviewdfx/hitrace
├── frameworks            # Framework code
│   └── native            # HiTrace Native implementation code
├── interfaces            # APIs
│   └── js                # JS APIs
│       └── kits          # JS inner implementation code 
│   └── native            # C/C++ APIs
│       └── innerkits     # Header files opened to internal subsystems
└── test                  # Test cases
```

## Constraints<a name="section119744591305"></a>

HiTrace is already supported by the IPC and EventHandler communication mechanisms. If you are using a custom communication mechanism, adaptation is required to use HiTrace.

## Usage<a name="section1312121216216"></a>

### Available APIs<a name="section1551164914237"></a>

Major APIs of HiTrace

<table><tbody><tr id="row1370464111219"><td class="cellrowborder" valign="top" width="8.98%"><a name="p1670474115124"></a><a name="p1670474115124"></a><a name="b13126192811515"></a><a name="b13126192811515"></a>Class
</td>
<td class="cellrowborder" valign="top" width="27.47%"><a name="p167041041191214"></a><a name="p167041041191214"></a><a name="b93135237153"></a><a name="b93135237153"></a>API
</td>
<td class="cellrowborder" valign="top" width="63.55%"><a name="p970484112122"></a><a name="p970484112122"></a><a name="b4370358151913"></a><a name="b4370358151913"></a>Description
</td>
</tr>
<tr id="row970417418126"><td class="cellrowborder" rowspan="2" valign="top" width="8.98%"><a name="p16704184111220"></a><a name="p16704184111220"></a>HiTrace
</td>
<td class="cellrowborder" valign="top" width="27.47%"><a name="p1270444181220"></a><a name="p1270444181220"></a>HiTraceId begin(String name, int flags)
</td>
<td class="cellrowborder" valign="top" width="63.55%"><a name="p20704144114123"></a><a name="p20704144114123"></a>Starts call chain tracing, generates a <a name="b52151451154412"></a><a name="b52151451154412"></a>HiTraceId object, and sets it in the TLS of the calling thread.
<a name="p1270494114128"></a><a name="p1270494114128"></a>Input parameters:
<a name="p370434151220"></a><a name="p370434151220"></a><a name="b1586330121717"></a><a name="b1586330121717"></a>name: Indicates the name of the service process.
<a name="p9704104181212"></a><a name="p9704104181212"></a><a name="b10973143151713"></a><a name="b10973143151713"></a>flags: Indicates call chain flags, which can be used in combination. 
<a name="p187046416125"></a><a name="p187046416125"></a><a name="b3332144316176"></a><a name="b3332144316176"></a>HITRACE_FLAG_INCLUDE_ASYNC: Traces both synchronous and asynchronous calls. By default, only synchronous calls are traced.
<a name="p12704104121212"></a><a name="p12704104121212"></a><a name="b17906163911715"></a><a name="b17906163911715"></a>HITRACE_FLAG_DONOT_CREATE_SPAN: Do note create a span. By default, a span is created.
<a name="p17704104171210"></a><a name="p17704104171210"></a><a name="b16819174510193"></a><a name="b16819174510193"></a>HITRACE_FLAG_TP_INFO: Outputs the tracepoint information. By default, the tracepoint information is not output.
<a name="p97041241181215"></a><a name="p97041241181215"></a><a name="b15542450201714"></a><a name="b15542450201714"></a>HITRACE_FLAG_NO_BE_INFO: Do not output the start and end information. By default, the information is output.
<a name="p47041241151211"></a><a name="p47041241151211"></a><a name="b68075771720"></a><a name="b68075771720"></a>HITRACE_FLAG_DONOT_ENABLE_LOG: Do not associate logs for output. By default, logs are associated for output.
<a name="p147041741141215"></a><a name="p147041741141215"></a><a name="b11871181131812"></a><a name="b11871181131812"></a>HITRACE_FLAG_FAULT_TRIGGER: Triggers call chain tracing by fault. By default, call chain tracing is triggered normally.
<a name="p2704164181214"></a><a name="p2704164181214"></a><a name="b59161113131816"></a><a name="b59161113131816"></a>HITRACE_FLAG_D2D_TP_INFO: Outputs inter-device tracepoint information. By default, the tracepoint information is not output.
<a name="p17704941121210"></a><a name="p17704941121210"></a><a name="b20659623501"></a><a name="b20659623501"></a>HITRACE_FLAG_DEFAULT: Indicates the default flag.
<a name="p17704174141216"></a><a name="p17704174141216"></a>Output parameters: none
<a name="p07045418125"></a><a name="p07045418125"></a>Return value: Returns a valid <a name="b149053347524"></a><a name="b149053347524"></a>HiTraceId object if call chain tracing is triggered successfully; returns an invalid object otherwise.
<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.
</td>
</tr>
<tr id="row18704194111211"><td class="cellrowborder" valign="top"><a name="p11704641131213"></a><a name="p11704641131213"></a>void end(HiTraceId id)
</td>
<td class="cellrowborder" valign="top"><a name="p20704144141212"></a><a name="p20704144141212"></a>Stops call chain tracing based on the <a name="b109681242310"></a><a name="b109681242310"></a>HiTraceId object returned by the <a name="b171995411436"></a><a name="b171995411436"></a>Begin API, and clears the <a name="b87181818247"></a><a name="b87181818247"></a>HiTraceId object in the TLS of the calling thread.
<a name="p7704174181215"></a><a name="p7704174181215"></a>Input parameters:
<a name="p14704134111216"></a><a name="p14704134111216"></a><a name="b15542231182"></a><a name="b15542231182"></a>id: Indicates the <a name="b046517501252"></a><a name="b046517501252"></a>HiTraceId object.
<a name="p15704104111215"></a><a name="p15704104111215"></a>Output parameters: none
<a name="p16704741181213"></a><a name="p16704741181213"></a>Return value: none
</td>
</tr>
</tbody>
</table>

## Repositories Involved<a name="section1371113476317"></a>

[DFX SubSystem](https://gitee.com/openharmony/docs/blob/master/en/readme/dfx.md)

[hiviewdfx\_hiview](https://gitee.com/openharmony/hiviewdfx_hiview/blob/master/README.md)

[hiviewdfx\_hilog](https://gitee.com/openharmony/hiviewdfx_hilog/blob/master/README.md)

[hiviewdfx\_hiappevent](https://gitee.com/openharmony/hiviewdfx_hiappevent/blob/master/README.md)

[hiviewdfx\_hisysevent](https://gitee.com/openharmony/hiviewdfx_hisysevent/blob/master/README.md)

Federer-JC/hiviewdfx_hitrace_1108

简介

发行版

贡献者

近期动态

Federer-JC/hiviewdfx_hitrace_1108 .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

Federer-JC/hiviewdfx_hitrace_1108