# HiTrace Development - [Overview](#section3986195420436) - [Use Cases](#section134561822574) - [Usage Example](#section63861653124417) - [Available APIs](#section1517945334617) - [Java, C++, and C APIs](#section932504474) - [Parameters of C++ APIs](#section2514638125) - [Call Chain Processing](#section11257133933) - [How to Develop](#section14310412491) - [C++](#section114916381509) - [C](#section108292107514) ## Overview 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. ## Use Cases HiTrace 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. - Works with the IDE to debug the detailed service process and time consumption distribution for system optimization. **Figure 1** Use cases of HiTrace ![](figure/use-cases-of-hitrace.png "use-cases-of-hitrace") ### Usage Example **Figure 2** Service calling process \(inter-device and inter-process synchronous call\) ![](figure/service-calling-process-(inter-device-and-inter-process-synchronous-call).png "service-calling-process-(inter-device-and-inter-process-synchronous-call)") 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. **Figure 3** Service calling process ![](figure/service-calling-process.png "service-calling-process") **Figure 4** Time delay in the service calling process ![](figure/time-delay-in-the-service-calling-process.png "time-delay-in-the-service-calling-process") 2. Add **traceid** to logs and events automatically to facilitate comprehensive analysis and quick fault location. ## Available APIs HiTrace provides C++ and C APIs. The upper-layer services mainly use HiTrace 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. ### Java, C++, and C APIs **Table 1** Description of C++ and C APIs
  

C++

C

Class

API

API

HiTrace

HiTraceId Begin(const std::string& name, int flags)

HiTraceIdStruct HiTraceBegin(const char* name, int flags)

void End(const HiTraceId& id)

void HiTraceEnd(const HiTraceIdStruct* pId)

HiTraceId GetId();

HiTraceIdStruct HiTraceGetId()

void SetId(const HiTraceId& id)

void HiTraceSetId(const HiTraceIdStruct* pId)

void ClearId()

void HiTraceClearId()

HiTraceId CreateSpan()

HiTraceIdStruct HiTraceCreateSpan()

void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

void HiTraceTracepoint(HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...)

void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

void HiTraceTracepointEx(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceIdStruct* pId, const char* fmt, ...)

HiTraceId

HiTraceId();

void HiTraceInitId(HiTraceIdStruct* pId)

HiTraceId(const uint8_t* pIdArray, int len)

HiTraceIdStruct HiTraceBytesToId(const uint8_t* pIdArray, int len)

bool IsValid()

int HiTraceIsValid(const HiTraceIdStruct* pId)

bool IsFlagEnabled(HiTraceFlag flag)

int HiTraceIsFlagEnabled(const HiTraceIdStruct* pId, HiTraceFlag flag)

void EnableFlag(HiTraceFlag flag)

void HiTraceEnableFlag(HiTraceIdStruct* pId, HiTraceFlag flag)

int GetFlags()

int HiTraceGetFlags(const HiTraceIdStruct* pId)

void SetFlags(int flags)

void HiTraceSetFlags(HiTraceIdStruct* pId, int flags)

uint64_t GetChainId()

uint64_t HiTraceGetChainId(const HiTraceIdStruct* pId)

void SetChainId(uint64_t chainId)

void HiTraceSetChainId(HiTraceIdStruct* pId, uint64_t chainId)

uint64_t GetSpanId()

uint64_t HiTraceGetSpanId(const HiTraceIdStruct* pId)

void SetSpanId(uint64_t spanId)

void HiTraceSetSpanId(HiTraceIdStruct* pId, uint64_t spanId)

uint64_t GetParentSpanId()

uint64_t HiTraceGetParentSpanId(const HiTraceIdStruct* pId)

void SetParentSpanId(uint64_t parentSpanId)

void HiTraceSetParentSpanId(HiTraceIdStruct* pId, uint64_t parentSpanId)

int ToBytes(uint8_t* pIdArray, int len)

int HiTraceIdToBytes(const HiTraceIdStruct* pId, uint8_t* pIdArray, int len)
### Parameters of C++ APIs **Table 2** Parameters of C++ APIs

Class

API

Description

HiTrace

HiTraceId Begin(const std::string& name, int flags)

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

Input arguments:

  • name: Indicates the name of the service process.
  • flags: Indicates tracing 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 not create a span. By default, a span is created.
    • HITRACE_FLAG_TP_INFO: Outputs the tracepoint information. By default, the 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 tracing by fault. By default, tracing is triggered normally.
    • HITRACE_FLAG_D2D_TP_INFO: Outputs the device-to-device tracepoint information. By default, the information is not output.
    • HITRCE_FLAG_DEFAULT: Indicates the default flag.
  • Output arguments: 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(const HiTraceId& id)

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

Input arguments:

  • id: Indicates the HiTraceId object.

Output arguments: none

Return value: none

HiTraceId GetId();

Obtains the HiTraceId object from the TLS of the calling thread.

Input arguments: none

Output arguments: none

Return value: Returns the 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.

Input arguments:

  • id: Indicates the HiTraceId object.

Output arguments: none

Return value: none

void ClearId()

Clears the HiTraceId object in the TLS of the current thread.

Input arguments: none

Output arguments: none

Return value: none

HiTraceId CreateSpan()

Obtains the span ID from the current HiTraceId object.

Input arguments: none

Output arguments: none

Return value: Returns the current span ID.

void Tracepoint(HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

Outputs HiTrace call chain information based on the information type. The information includes the timestamp and HiTraceId object information of the span.

Input arguments:

  • type: Indicates the information type. The options are as follows:
    • HITRACE_TP_CS: Client Send, which indicates the messages sent by the synchronous/asynchronous communication client.
    • HITRACE_TP_SR: Server Receive, which indicates the messages received by the server in synchronous/asynchronous communication.
    • HITRACE_TP_SS: Server Send, which indicates the response messages sent by the server in synchronous communication.
    • HITRACE_TP_CR: Client Receive, which indicates the response messages received by the synchronous communication client.
    • HITRACE_TP_GENERAL: Indicates the common output information.
  • id: Indicates the ID of the current span.
  • fmt: Indicates the string describing the format variable parameter.
  • args: Indicates the variable parameter.

Output arguments: none

Return value: none

void Tracepoint(HiTraceCommunicationMode mode, HiTraceTracepointType type, const HiTraceId& id, const char* fmt, ...)

Outputs HiTrace call chain information based on the communication mode and information type. The information includes the timestamp and HiTraceId object information of the span.

Input arguments:

  • mode: Indicates the communication mode. The options are as follows:
    • HITRACE_CM_DEFAULT: default communication mode used when no communication mode is specified
    • HITRACE_CM_THREAD: inter-thread communication
    • HITRACE_CM_PROCESS: inter-process communication
    • HITRACE_CM_DEVICE: inter-device communication
  • type: Indicates the information type. The options are as follows:
    • HITRACE_TP_CS: Client Send, which indicates the messages sent by the synchronous/asynchronous communication client.
    • HITRACE_TP_SR: Server Receive, which indicates the messages received by the server in synchronous/asynchronous communication.
    • HITRACE_TP_SS: Server Send, which indicates the response messages sent by the server in synchronous communication.
    • HITRACE_TP_CR: Client Receive, which indicates the response messages received by the synchronous communication client.
    • HITRACE_TP_GENERAL: Indicates the common output information.
  • id: Indicates the ID of the current span.
  • fmt: Indicates the string describing the format variable parameter.
  • args: Indicates the variable parameter.

Output arguments: none

Return value: none

HiTraceId

HiTraceId();

Represents the default constructor used to generate an invalid HiTraceId object.

Input arguments: none

Output arguments: none

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.

Input arguments:
  • pIdArray: Indicates the pointer to a byte array.
  • len: Indicates the length of the byte array.

Output arguments: none

Return value: none

bool IsValid()

Checks whether the HiTraceId object is valid.

Input arguments: none

Output arguments: none

Return value: Returns true if the HiTraceId object is valid; returns false otherwise.

bool IsFlagEnabled(HiTraceFlag flag)

Checks whether the tracing flag of the HiTraceId object is enabled.

Input arguments:

  • flag: Indicates the tracing flag. For details, see the description in the Begin function.

Output arguments: none

Return value: Returns true if the tracing flag is enabled; returns false otherwise.

void EnableFlag(HiTraceFlag flag)

Enables the tracing flag of the HiTraceId object.

Input arguments:

  • flag: Indicates the tracing flag. For details, see the description in the Begin function.

Output arguments: none

Return value: none

int GetFlags()

Obtains the tracing flag set in the HiTraceId object.

Input arguments: none

Output arguments: none

Return value: Returns the combination of tracing flags. For details, see the description in the Begin function.

void SetFlags(int flags)

Sets a tracing flag in the HiTraceId object.

Input arguments:

  • flags: Indicates the combination of tracing flags. For details, see the description in the Begin function.

Output arguments: none

Return value: none

uint64_t GetChainId()

Obtains the call chain ID.

Input arguments: none

Output arguments: none

Return value: Returns the call chain ID.

void SetChainId(uint64_t chainId)

Sets the call chain ID in the HiTraceId object.

Input arguments:

  • chainId: Indicates the call chain ID.

Output arguments: none

Return value: none

uint64_t GetSpanId()

Obtains the span ID from the current HiTraceId object.

Input arguments: none

Output arguments: none

Return value: Returns the current span ID.

void SetSpanId(uint64_t spanId)

Sets the span ID in the HiTraceId object.

Input arguments:

  • spanId: Indicates the span ID.

Output arguments: none

Return value: none

uint64_t GetParentSpanId()

Obtains the parent span ID from the current HiTraceId object.

Input arguments: none

Output arguments: none

Return value: Returns the parent span ID.

void SetParentSpanId(uint64_t parentSpanId)

Sets the parent span ID in the HiTraceId object.

Input arguments:

  • parentSpanId: Indicates the parent span ID.

Output arguments: none

Return value: none

int ToBytes(uint8_t* pIdArray, int len)

Converts the HiTraceId object into a byte array to facilitate caching or communication transfer.

Input arguments:

  • pIdArray: Indicates the pointer to a byte array. The minimum length of the byte array is HITRACE_ID_LEN.
  • len: Indicates the length of the byte array.

Output arguments

  • pIdArray: Indicates the pointer to a byte array. If the object is valid, the object data after conversion is stored.

Return value: Returns a value greater than 0 (indicating a valid array of object data) if the conversion is successful; returns 0 otherwise.
## Call Chain Processing Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. **HiTrace** 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 ![](figure/call-chain-tracing-in-synchronous-communication.png "call-chain-tracing-in-synchronous-communication") The process is as follows: 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. Include the **hitrace** header file in the class definition header file or class implementation source file. For example: ``` #include "hitrace/trace.h" ``` Add the code to start and stop call chain tracing in the class implementation source file. ``` using namespace OHOS::HiviewDFX; HiTraceId traceId = HiTrace::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT); ... HiTrace::End(traceId); ``` 2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. ``` external_deps = [ "hiviewdfx:libhitrace" ] ``` ### C 1. Develop the source code. Include the **hitrace** header file in the source file. ``` #include "hitrace/trace.h" ``` Add the code to start and stop call chain tracing in the class implementation source file. ``` HiTraceIdStruct traceId = HiTraceBegin("MyServiceFlow", HITRACE_FLAG_DEFAULT); ... HiTraceEnd(traceId); ``` 2. Configure compilation information. Specifically, add the subsystem SDK dependency to **BUILD.gn**. ``` external_deps = [ "hiviewdfx:libhitrace" ] ```