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.
Usage Example
Figure 2 Service calling process (inter-device and inter-process synchronous call)
-
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.
-
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
Parameters of C++ APIs
Table 2 Parameters of C++ APIs
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:
-
The service module on the client calls the begin() function to start call chain tracing.
-
The service module on the client synchronously calls the transact function to the communication component on the client.
-
The communication component on the client performs the following:
- Obtains traceid from the TLS of the calling thread.
- Generates child traceid.
- Writes child traceid into the transaction data (synchronous communication data).
- Performs Client Send (CS) tracing.
- Sends communication data to the communication component on the server.
-
On receiving the communication data, the communication component on the server performs the following:
- Obtains traceid from the data message package.
- Sets traceid in the TLS of the calling thread.
- Performs Server Receive (SR) tracing.
- Synchronously call the onTransact callback to the service module on the server.
-
The service module on the server processes the service and sends the transact reply message carrying the processing result to the communication component.
-
The communication component on the server performs the following:
- Performs Server Send (SS) tracing.
- Sends communication data to the communication component on the client.
- Clears traceid from the TLS of the calling thread.
-
On receiving the communication data, the communication component on the client performs the following:
- Performs Client Receive (CR) tracing.
- Sends a transact reply response to the service module on the client.
-
The service module on the client processes the transact reply response.
-
When the process ends, the service module on the client calls the end() function to stop call chain tracing.
How to Develop
C++
-
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);
-
Configure compilation information. Specifically, add the subsystem SDK dependency to BUILD.gn.
external_deps = [ "hiviewdfx:libhitrace" ]
C
-
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);
-
Configure compilation information. Specifically, add the subsystem SDK dependency to BUILD.gn.
external_deps = [ "hiviewdfx:libhitrace" ]