HiTrace

• Overview

• Architecture

• Directory Structure

• Constraints

• Usage

  • Available APIs
  • Usage Guidelines

• Repositories Involved

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

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
│   ├── java            # HiTrace Java implementation code
│   ├── jni             # HiTrace JNI implementation code
│   └── native          # HiTrace Native implementation code
└── interfaces           # APIs
   ├── java              # Java APIs
   │   ├── innerkits    # JAR packages opened to internal subsystems
   │   └── kits         # JAR packages opened to applications
   └── native            # C/C++ APIs
       └── innerkits     # Header files opened to internal subsystems

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

Usage Guidelines

1 Enable call chain tracing for the service process.

Import the HiTrace and HiTraceId classes.

import ohos.hiviewdfx.HiTrace;
import ohos.hiviewdfx.HiTraceId;

Add the code to start or stop call chain tracing.

HiTraceId traceId = HiTrace.begin("MyServiceFlow", HiTrace.HITRACE_FLAG_DEFAULT);
... (service process for call chain tracing)
HiTrace.end(traceId);

2 Run the application.

3 Use the hilog tool in the shell to filter logs of the service invoking process.

Filter logs based on the name parameter in the tracing task and find ChainId.

hilog | grep "MyServiceFlow"

Note: The log format for traceid is as follows:

Time PID TID Level Domain/Tag: [ChainId, SpanId, ParentSpanId] Content

Filter the logs of the service invoking process based on ChainId.

hilog | grep "ChainId"

Repositories Involved

Hivew

HiDumper