HiTrace Development

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

Usage Example

Figure 2 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 4 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

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" ]