HiTraceChain Development

Overview

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

When to Use

HiTraceChain 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 HiTraceChain

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

HiTraceChain provides C++ and C APIs. The upper-layer services mainly use HiTraceChain to start and stop call chain trace.

HiTraceChain 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

Parameters of C++ APIs

Table 2 Trace flag combination types

Table 3 Trace point types

Table 4 Communication modes

Table 5 Description of C++ APIs

Call Chain Processing

Inter-device, inter-process, and inter-thread calls are implemented through the communication mechanism. HiTraceChain 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 trace in synchronous communication

The process is as follows:

1. The service module on the client calls the begin() function to start call chain trace.

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 CS trace.
   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 SR trace.
   4. Synchronously calls 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 SS trace.
   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 CR trace.
   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 trace.

How to Develop

C++

1. Develop the source code. Include the hitracechain header file in the class definition header file or class implementation source file. For example:

   #include "hitrace/tracechain.h"
   

   Add the code to start and stop call chain trace in the class implementation source file.

   using namespace OHOS::HiviewDFX;
   auto traceId = HiTraceChain::Begin("MyServiceFlow", HITRACE_FLAG_DEFAULT);
   ......
   HiTraceChain::End(traceId);
   

2. Configure compilation information. Specifically, add the subsystem SDK dependency to BUILD.gn.

   external_deps = [ "hitrace:libhitracechain" ]
   

C

1. Develop the source code. Include the hitracechain header file in the source file.

   #include "hitrace/tracechain.h"
   

   Add the code to start and stop call chain trace in the class implementation source file.

   HiTraceIdStruct traceId = HiTraceChainBegin("MyServiceFlow", HITRACE_FLAG_DEFAULT);
   ......
   HiTraceChainEnd(traceId);
   

2. Configure compilation information. Specifically, add the subsystem SDK dependency to BUILD.gn.

   external_deps = [ "hitrace:libhitracechain" ]