harmony 鸿蒙trace.h

2025-06-12
浏览 (6)

trace.h

Overview

Defines APIs of the HiTraceMeter module for performance trace.

The vertical bar (|) is used as the separator in user-mode trace format. Therefore, the string parameters passed by the HiTraceMeter APIs must exclude this character to avoid trace parsing exceptions.

The maximum length of a user-mode trace is 512 characters. Excess characters will be truncated.

Library: libhitrace_ndk.z.so

File to include:

System capability: SystemCapability.HiviewDFX.HiTrace

Since: 10

Related module: HiTrace

Summary

Structs

Name	Description
struct  HiTraceId	Defines a HiTraceId instance.

Types

Name	Description
typedef enum HiTraceId_Valid HiTraceId_Valid	Defines an enum for whether a HiTraceId instance is valid.
typedef enum HiTrace_Version HiTrace_Version	Defines an enum for the HiTrace versions.
typedef enum HiTrace_Flag HiTrace_Flag	Defines an enum for the HiTrace flags.
typedef enum HiTrace_Tracepoint_Type HiTrace_Tracepoint_Type	Defines an enum for the HiTrace tracepoint types.
typedef enum HiTrace_Communication_Mode HiTrace_Communication_Mode	Defines an enum for the HiTrace communication modes.
typedef struct HiTraceId HiTraceId	Defines a struct for the HiTrace ID.
typedef enum HiTrace_Output_Level HiTrace_Output_Level	Defines an enum for the HiTrace output levels.

Enums

Name	Description
HiTraceId_Valid { HITRACE_ID_INVALID = 0, HITRACE_ID_VALID = 1 }	Enumerates whether a HiTraceId instance is valid.
HiTrace_Version { HITRACE_VER_1 = 0 }	Enumerates the HiTrace versions.
HiTrace_Flag { HITRACE_FLAG_DEFAULT = 0, HITRACE_FLAG_INCLUDE_ASYNC = 1 << 0, HITRACE_FLAG_DONOT_CREATE_SPAN = 1 << 1, HITRACE_FLAG_TP_INFO = 1 << 2, HITRACE_FLAG_NO_BE_INFO = 1 << 3, HITRACE_FLAG_DONOT_ENABLE_LOG = 1 << 4, HITRACE_FLAG_FAULT_TRIGGER = 1 << 5, HITRACE_FLAG_D2D_TP_INFO = 1 << 6 }	Enumerates the HiTrace flags.
HiTrace_Tracepoint_Type { HITRACE_TP_CS = 0, HITRACE_TP_CR = 1, HITRACE_TP_SS = 2, HITRACE_TP_SR = 3, HITRACE_TP_GENERAL = 4 }	Enumerates the HiTrace tracepoint types.
HiTrace_Communication_Mode { HITRACE_CM_DEFAULT = 0, HITRACE_CM_THREAD = 1, HITRACE_CM_PROCESS = 2, HITRACE_CM_DEVICE = 3 }	Enumerates the HiTrace communication modes.
HiTrace_Output_Level { HITRACE_LEVEL_DEBUG = 0, HITRACE_LEVEL_INFO = 1, HITRACE_LEVEL_CRITICAL = 2, HITRACE_LEVEL_COMMERCIAL = 3, HITRACE_LEVEL_MAX = HITRACE_LEVEL_COMMERCIAL}	Enumerates the HiTrace output levels.

Functions

Name	Description
HiTraceId OH_HiTrace_BeginChain (const char *name, int flags)	Starts tracing a process.
void OH_HiTrace_EndChain ()	Stops tracing the process and clears the trace ID of the calling thread if the given trace ID is valid. Otherwise, no operation is performed.
HiTraceId OH_HiTrace_GetId ()	Obtains the trace ID of the calling thread. If the calling thread does not have a trace ID, an invalid trace ID is returned.
void OH_HiTrace_SetId (const HiTraceId *id)	Sets the trace ID of the calling thread. If the ID is invalid, no operation is performed.
void OH_HiTrace_ClearId (void)	Clears the trace ID of the calling thread and invalidates it.
HiTraceId OH_HiTrace_CreateSpan (void)	Creates a span ID based on the trace ID of the calling thread.
void OH_HiTrace_Tracepoint (HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId id, const char fmt,…)	Prints HiTrace information, including the trace ID.
void OH_HiTrace_InitId (HiTraceId *id)	Initializes a HiTraceId instance.
void OH_HiTrace_IdFromBytes (HiTraceId id, const uint8_t pIdArray, int len)	Creates a HiTraceId instance based on a byte array.
bool OH_HiTrace_IsIdValid (const HiTraceId *id)	Checks whether a HiTraceId instance is valid.
bool OH_HiTrace_IsFlagEnabled (const HiTraceId *id, HiTrace_Flag flag)	Checks whether the specified trace flag is enabled in a HiTraceId instance.
void OH_HiTrace_EnableFlag (const HiTraceId *id, HiTrace_Flag flag)	Enables the specified trace flag in a HiTraceId instance.
int OH_HiTrace_GetFlags (const HiTraceId *id)	Obtains the trace flags in a HiTraceId instance.
void OH_HiTrace_SetFlags (HiTraceId *id, int flags)	Sets trace flags in a HiTraceId instance.
uint64_t OH_HiTrace_GetChainId (const HiTraceId *id)	Obtains a trace chain ID.
void OH_HiTrace_SetChainId (HiTraceId *id, uint64_t chainId)	Sets the trace chain ID in a HiTraceId instance.
uint64_t OH_HiTrace_GetSpanId (const HiTraceId *id)	Obtains the span ID in a HiTraceId instance.
void OH_HiTrace_SetSpanId (HiTraceId *id, uint64_t spanId)	Sets the span ID in a HiTraceId instance.
uint64_t OH_HiTrace_GetParentSpanId (const HiTraceId *id)	Obtains the parent span ID in a HiTraceId instance.
void OH_HiTrace_SetParentSpanId (HiTraceId *id, uint64_t parentSpanId)	Sets the ParentSpanId in a HiTraceId instance.
int OH_HiTrace_IdToBytes (const HiTraceId id, uint8_t pIdArray, int len)	Converts a HiTraceId instance into a byte array for caching or transfer.
void OH_HiTrace_StartTrace (const char *name)	Marks the start of a synchronous trace.
void OH_HiTrace_FinishTrace (void)	Marks the end of a synchronous trace.
void OH_HiTrace_StartAsyncTrace (const char *name, int32_t taskId)	Marks the start of an asynchronous trace.
void OH_HiTrace_FinishAsyncTrace (const char *name, int32_t taskId)	Marks the end of an asynchronous trace.
void OH_HiTrace_CountTrace (const char *name, int64_t count)	Traces the value change of an integer variable based on its name.
void OH_HiTrace_StartTraceEx (HiTrace_Output_Level level, const char name, const char customArgs)	Marks the start of a synchronous trace task with the trace output level specified.
void OH_HiTrace_FinishTraceEx (HiTrace_Output_Level level)	Marks the end of a synchronous trace task with the trace output level specified.
void OH_HiTrace_StartAsyncTraceEx (HiTrace_Output_Level level, const char name, int32_t taskId, const char customCategory, const char *customArgs)	Marks the start of an asynchronous trace task with the trace output level specified.
void OH_HiTrace_FinishAsyncTraceEx (HiTrace_Output_Level level, const char *name, int32_t taskId)	Marks the end of an asynchronous trace task with the trace output level specified.
void OH_HiTrace_CountTraceEx (HiTrace_Output_Level level, const char *name, int64_t count)	Marks an integer variable trace task with the trace output level specified.
bool OH_HiTrace_IsTraceEnabled (void)	Checks whether trace capture is enabled for an application. If not, HiTraceMeter performance tracing is invalid.