harmony 鸿蒙trace.h

2025-06-16
浏览 (2)

trace.h

概述

HiTraceMeter模块打点接口定义，通过这些接口实现性能打点相关功能。

用户态tarce格式使用竖线|作为分隔符，所以通过HiTraceMeter接口传递的字符串类型参数应避免包含该字符，防止trace解析异常。

用户态trace总长度限制512字符，超过的部分将会被截断。

库： libhitrace_ndk.z.so

引用文件：

系统能力： SystemCapability.HiviewDFX.HiTrace

起始版本： 10

相关模块：Hitrace

汇总

结构体

名称	描述
struct  HiTraceId	HiTraceId定义。

类型定义

名称	描述
typedef enum HiTraceId_Valid HiTraceId_Valid	HiTraceId是否有效标志。
typedef enum HiTrace_Version HiTrace_Version	HiTrace版本号。
typedef enum HiTrace_Flag HiTrace_Flag	HiTrace标志位。
typedef enum HiTrace_Tracepoint_Type HiTrace_Tracepoint_Type	HiTrace打点类型。
typedef enum HiTrace_Communication_Mode HiTrace_Communication_Mode	HiTrace通信模式枚举。
typedef struct HiTraceId HiTraceId	系统跟踪Id。
typedef enum HiTrace_Output_Level HiTrace_Output_Level	HiTrace输出级别。

枚举

名称	描述
HiTraceId_Valid { HITRACE_ID_INVALID = 0, HITRACE_ID_VALID = 1 }	HiTraceId是否有效标志。
HiTrace_Version { HITRACE_VER_1 = 0 }	HiTrace版本号。
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 }	HiTrace标志位。
HiTrace_Tracepoint_Type { HITRACE_TP_CS = 0, HITRACE_TP_CR = 1, HITRACE_TP_SS = 2, HITRACE_TP_SR = 3, HITRACE_TP_GENERAL = 4 }	HiTrace打点类型。
HiTrace_Communication_Mode { HITRACE_CM_DEFAULT = 0, HITRACE_CM_THREAD = 1, HITRACE_CM_PROCESS = 2, HITRACE_CM_DEVICE = 3 }	HiTrace通信模式枚举。
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}	HiTrace输出级别。

函数

名称	描述
HiTraceId OH_HiTrace_BeginChain (const char *name, int flags)	开始跟踪进程实现。
void OH_HiTrace_EndChain ()	如果给定的跟踪ID有效，则停止进程跟踪并清除当前线程的跟踪ID，否则不执行任何操作。
HiTraceId OH_HiTrace_GetId ()	获取当前线程的跟踪ID，如果没有属于当前线程的跟踪ID，则返回一个无效的跟踪ID。
void OH_HiTrace_SetId (const HiTraceId *id)	将id设置为当前线程的跟踪id。如果ID无效，则不执行任何操作。
void OH_HiTrace_ClearId (void)	清除当前线程的跟踪ID并将其设置为无效。
HiTraceId OH_HiTrace_CreateSpan (void)	根据当前线程的跟踪id创建一个新的span id。
void OH_HiTrace_Tracepoint (HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId id, const char fmt,…)	打印hitrace信息，包括跟踪ID信息。
void OH_HiTrace_InitId (HiTraceId *id)	初始化HiTraceId结构体。
void OH_HiTrace_IdFromBytes (HiTraceId id, const uint8_t pIdArray, int len)	根据字节数组创建跟踪HiTraceId结构体。
bool OH_HiTrace_IsIdValid (const HiTraceId *id)	判断trace id是否有效。
bool OH_HiTrace_IsFlagEnabled (const HiTraceId *id, HiTrace_Flag flag)	判断跟踪id是否启用了跟踪标志。
void OH_HiTrace_EnableFlag (const HiTraceId *id, HiTrace_Flag flag)	启用跟踪ID的指定跟踪标志。
int OH_HiTrace_GetFlags (const HiTraceId *id)	获取HiTraceId结构体中设置的标志位。
void OH_HiTrace_SetFlags (HiTraceId *id, int flags)	设置跟踪标志位到HiTraceId结构体中。
uint64_t OH_HiTrace_GetChainId (const HiTraceId *id)	获取跟踪链ID。
void OH_HiTrace_SetChainId (HiTraceId *id, uint64_t chainId)	设置跟踪链ID到HiTraceId结构体中。
uint64_t OH_HiTrace_GetSpanId (const HiTraceId *id)	获取当前HiTraceId结构体中的分支ID。
void OH_HiTrace_SetSpanId (HiTraceId *id, uint64_t spanId)	设置分支ID到HiTraceId结构体中。
uint64_t OH_HiTrace_GetParentSpanId (const HiTraceId *id)	获取当前HiTraceId结构体中的父分支ID。
void OH_HiTrace_SetParentSpanId (HiTraceId *id, uint64_t parentSpanId)	设置HiTraceId结构的parentSpanId字符。
int OH_HiTrace_IdToBytes (const HiTraceId id, uint8_t pIdArray, int len)	将HiTraceId结构体转换为字节数组，用于缓存或者通信传递。
void OH_HiTrace_StartTrace (const char *name)	标记一个同步跟踪耗时任务的开始。
void OH_HiTrace_FinishTrace (void)	标记一个同步跟踪耗时任务的结束。
void OH_HiTrace_StartAsyncTrace (const char *name, int32_t taskId)	标记一个异步跟踪耗时任务的开始。
void OH_HiTrace_FinishAsyncTrace (const char *name, int32_t taskId)	标记一个异步跟踪耗时任务的结束。
void OH_HiTrace_CountTrace (const char *name, int64_t count)	用于跟踪给定整数变量名和整数值。
void OH_HiTrace_StartTraceEx (HiTrace_Output_Level level, const char name, const char customArgs)	标记一个同步跟踪耗时任务的开始，分级控制跟踪输出。
void OH_HiTrace_FinishTraceEx (HiTrace_Output_Level level)	标记一个同步跟踪耗时任务的结束，分级控制跟踪输出。
void OH_HiTrace_StartAsyncTraceEx (HiTrace_Output_Level level, const char name, int32_t taskId, const char customCategory, const char *customArgs)	标记一个异步跟踪耗时任务的开始，分级控制跟踪输出。
void OH_HiTrace_FinishAsyncTraceEx (HiTrace_Output_Level level, const char *name, int32_t taskId)	标记一个异步跟踪耗时任务的结束，分级控制跟踪输出。
void OH_HiTrace_CountTraceEx (HiTrace_Output_Level level, const char *name, int64_t count)	标记一个跟踪的整数变量，分级控制跟踪输出。
bool OH_HiTrace_IsTraceEnabled (void)	判断当前是否开启应用trace捕获。应用trace捕获未开启时，HiTraceMeter性能跟踪打点无效。