# HiTrace - [Overview](#section11660541593) - [Architecture](#section16334748141112) - [Directory Structure](#section161941989596) - [Constraints](#section119744591305) - [Usage](#section1312121216216) - [Available APIs](#section1551164914237) - [Usage Guidelines](#section129654513264) - [Repositories Involved](#section1371113476317) ## Overview 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 **Figure 1** Architecture of HiTrace ![](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 ``` /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 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 ### Available APIs Major APIs of HiTrace

Class

API

Description

HiTrace

HiTraceId begin(String name, int flags)

Starts call chain tracing, generates a HiTraceId object, and sets it in the TLS of the calling thread.

Input parameters:

name: Indicates the name of the service process.

flags: Indicates call chain flags, which can be used in combination.

HITRACE_FLAG_INCLUDE_ASYNC: Traces both synchronous and asynchronous calls. By default, only synchronous calls are traced.

HITRACE_FLAG_DONOT_CREATE_SPAN: Do note create a span. By default, a span is created.

HITRACE_FLAG_TP_INFO: Outputs the tracepoint information. By default, the tracepoint information is not output.

HITRACE_FLAG_NO_BE_INFO: Do not output the start and end information. By default, the information is output.

HITRACE_FLAG_DONOT_ENABLE_LOG: Do not associate logs for output. By default, logs are associated for output.

HITRACE_FLAG_FAULT_TRIGGER: Triggers call chain tracing by fault. By default, call chain tracing is triggered normally.

HITRACE_FLAG_D2D_TP_INFO: Outputs inter-device tracepoint information. By default, the tracepoint information is not output.

HITRACE_FLAG_DEFAULT: Indicates the default flag.

Output parameters: none

Return value: Returns a valid HiTraceId object if call chain tracing is triggered successfully; returns an invalid object otherwise.

Note: In nested tracing mode, an invalid object will be returned if tracing is started at the nested layer.

void end(HiTraceId id)

Stops call chain tracing based on the HiTraceId object returned by the Begin API, and clears the HiTraceId object in the TLS of the calling thread.

Input parameters:

id: Indicates the HiTraceId object.

Output parameters: none

Return value: none

## Repositories Involved [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)