trace.h
概述
HiTraceMeter和HiTraceChain模块接口定义，通过这些接口实现性能打点和分布式跟踪功能。
用户态trace格式使用竖线字符作为分隔符，所以通过HiTraceMeter接口传递的字符串类型参数应避免包含该字符，防止trace解析异常。
用户态trace总长度限制512字符，超过的部分将会被截断。
引用文件： <hitrace/trace.h>
库： libhitrace_ndk.z.so
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 10
相关模块： Hitrace
汇总
结构体
| 名称 | typedef关键字 | 描述 |
|---|---|---|
| HiTraceId | HiTraceId | HiTraceId定义。 |
枚举
| 名称 | typedef关键字 | 描述 |
|---|---|---|
| HiTraceId_Valid | HiTraceId_Valid | HiTraceId是否有效标志。 |
| HiTrace_Version | HiTrace_Version | HiTrace版本号。 |
| HiTrace_Flag | HiTrace_Flag | HiTrace跟踪标志。 |
| HiTrace_Tracepoint_Type | HiTrace_Tracepoint_Type | 跟踪埋点类型枚举。 |
| HiTrace_Communication_Mode | HiTrace_Communication_Mode | 跟踪通信类型枚举。 |
| HiTrace_Output_Level | HiTrace_Output_Level | HiTrace输出级别。低于系统跟踪输出级别阈值的打点将不会生效。log版本阈值为HITRACE_LEVEL_INFO；nolog版本阈值为HITRACE_LEVEL_COMMERCIAL。 |
函数
枚举类型说明
HiTraceId_Valid
enum HiTraceId_Valid
描述
HiTraceId是否有效标志。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
| 枚举项 | 描述 |
|---|---|
| HITRACE_ID_INVALID = 0 | 无效HiTraceId。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_ID_VALID = 1 | 有效HiTraceId。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
HiTrace_Version
enum HiTrace_Version
描述
HiTrace版本号。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
| 枚举项 | 描述 |
|---|---|
| HITRACE_VER_1 = 0 | 版本1。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
HiTrace_Flag
enum HiTrace_Flag
描述
HiTrace跟踪标志。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
| 枚举项 | 描述 |
|---|---|
| HITRACE_FLAG_DEFAULT = 0 | 缺省标志。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_INCLUDE_ASYNC = 1 << 0 | 异步调用标志。 设置该标志，同时跟踪同步和异步调用；缺省只跟踪同步调用。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_DONOT_CREATE_SPAN = 1 << 1 | 无分支标志。 设置该标志，不创建分支信息；缺省创建分支信息。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_TP_INFO = 1 << 2 | 埋点标志。 调试场景下设置该标志，调用信息埋点接口OH_HiTrace_Tracepoint时，会打印埋点信息hilog日志；缺省不打印埋点信息hilog日志。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_NO_BE_INFO = 1 << 3 | 无开始结束信息标志。 调试场景下设置该标志，调用开始跟踪接口OH_HiTrace_BeginChain和结束跟踪接口OH_HiTrace_EndChain时，分别会打印开始、结束跟踪信息hilog日志；缺省不打印开始、结束跟踪信息hilog日志。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_DONOT_ENABLE_LOG = 1 << 4 | 日志关联标志。 设置该标志，不会在hilog日志中附加HiTraceId信息；缺省会在hilog日志中附加HiTraceId信息。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_FAULT_TRIGGER = 1 << 5 | 故障触发标志。预置标志，暂未启用。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_D2D_TP_INFO = 1 << 6 | 设备间埋点标志。HITRACE_FLAG_TP_INFO的一个子集，调试场景下使用。 当已设置HITRACE_FLAG_TP_INFO标志时，HITRACE_FLAG_D2D_TP_INFO标志不生效； 当未设置HITRACE_FLAG_TP_INFO标志时，设置HITRACE_FLAG_D2D_TP_INFO标志，此时调用信息埋点接口OH_HiTrace_Tracepoint，仅当mode参数为设备间通信HITRACE_CM_DEVICE的情况下，会打印埋点信息hilog日志。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
HiTrace_Tracepoint_Type
enum HiTrace_Tracepoint_Type
描述
跟踪埋点类型枚举。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
| 枚举项 | 描述 |
|---|---|
| HITRACE_TP_CS = 0 | 客户端发送。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_TP_CR = 1 | 客户端接收。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_TP_SS = 2 | 服务端发送。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_TP_SR = 3 | 服务端接收。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_TP_GENERAL = 4 | 通用类型，标识HITRACE_TP_CS、HITRACE_TP_CR、HITRACE_TP_SS、HITRACE_TP_SR四种场景之外的埋点。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
HiTrace_Communication_Mode
enum HiTrace_Communication_Mode
描述
跟踪通信类型枚举。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
| 枚举项 | 描述 |
|---|---|
| HITRACE_CM_DEFAULT = 0 | 缺省通信类型。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_CM_THREAD = 1 | 线程间通信。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_CM_PROCESS = 2 | 进程间通信。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
| HITRACE_CM_DEVICE = 3 | 设备间通信。 起始版本： 12 系统能力： SystemCapability.HiviewDFX.HiTrace |
HiTrace_Output_Level
enum HiTrace_Output_Level
描述
HiTrace输出级别。低于系统跟踪输出级别阈值的打点将不会生效。log版本阈值为HITRACE_LEVEL_INFO；nolog版本阈值为HITRACE_LEVEL_COMMERCIAL。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 19
| 枚举项 | 描述 |
|---|---|
| HITRACE_LEVEL_DEBUG = 0 | 仅用于调试的输出级别，优先级最低。 起始版本： 19 |
| HITRACE_LEVEL_INFO = 1 | 用于log版本的输出级别。 起始版本： 19 |
| HITRACE_LEVEL_CRITICAL = 2 | 用于log版本的输出级别，优先级高于HITRACE_LEVEL_INFO。 起始版本： 19 |
| HITRACE_LEVEL_COMMERCIAL = 3 | 用于nolog版本的输出级别，优先级最高。 起始版本： 19 |
| HITRACE_LEVEL_MAX = HITRACE_LEVEL_COMMERCIAL | 输出级别范围限制。 起始版本： 19 |
函数说明
OH_HiTrace_TraceEventListener()
typedef void (*OH_HiTrace_TraceEventListener)(bool traceStatus)
描述
定义应用trace捕获开关状态切换时的回调函数类型。
起始版本： 22
参数：
| 参数项 | 描述 |
|---|---|
| bool traceStatus | 当前应用trace捕获开关状态。 true：开启；false：关闭。 |
OH_HiTrace_BeginChain()
HiTraceId OH_HiTrace_BeginChain(const char *name, int flags)
描述
开始跟踪。
当前线程TLS（Thread Local Storage，线程本地存储）中不存在有效的HiTraceId时，生成有效的HiTraceId并设置到当前线程TLS中，返回该HiTraceId。
当前线程TLS中已存在有效的HiTraceId时，不会开始新的跟踪，返回各属性值均为0的无效HiTraceId。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const char *name | 跟踪业务名。 |
| int flags | 跟踪标志组合，见HiTrace_Flag。 |
返回：
| 类型 | 说明 |
|---|---|
| HiTraceId | HiTraceId结构体。 |
OH_HiTrace_EndChain()
void OH_HiTrace_EndChain()
描述
结束跟踪。
结束跟踪并将当前线程TLS中的HiTraceId设置为无效。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
OH_HiTrace_GetId()
HiTraceId OH_HiTrace_GetId()
描述
获取跟踪标识。
获取当前线程TLS中的HiTraceId。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
返回：
| 类型 | 说明 |
|---|---|
| HiTraceId | HiTraceId结构体。 |
OH_HiTrace_SetId()
void OH_HiTrace_SetId(const HiTraceId *id)
描述
设置跟踪标识。
将给定的HiTraceId设置到当前线程TLS中。若传入的参数无效，则不执行任何操作。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const HiTraceId *id | 要设置的HiTraceId。 |
OH_HiTrace_ClearId()
void OH_HiTrace_ClearId(void)
描述
清除跟踪标识。
将当前线程TLS中的HiTraceId设置为无效。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
OH_HiTrace_CreateSpan()
HiTraceId OH_HiTrace_CreateSpan(void)
描述
创建跟踪分支。
创建一个HiTraceId，使用当前线程TLS中的chainId、spanId初始化其chainId、parentSpanId，并为其生成一个新的spanId。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
返回：
| 类型 | 说明 |
|---|---|
| HiTraceId | HiTraceId结构体。 |
OH_HiTrace_Tracepoint()
void OH_HiTrace_Tracepoint(HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId *id, const char *fmt, ...)
描述
HiTraceMeter跟踪信息埋点。
type为客户端发送HITRACE_TP_CS和服务端接收HITRACE_TP_SR时，进行同步HiTraceMeter开始打点；type为客户端接收HITRACE_TP_CR和服务端发送HITRACE_TP_SS时，进行同步HiTraceMeter结束打点；type为通用类型HITRACE_TP_GENERAL时，不会进行HiTraceMeter打点。
type为客户端发送HITRACE_TP_CS和客户端接收HITRACE_TP_CR的信息埋点需配套使用；type为服务端接收HITRACE_TP_SR和服务端发送HITRACE_TP_SS的信息埋点需配套使用。否则，HiTraceMeter开始与结束打点无法正常匹配。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiTrace_Communication_Mode mode | 跟踪通信模式，见HiTrace_Communication_Mode。 |
| HiTrace_Tracepoint_Type type | 跟踪信息类型，见HiTrace_Tracepoint_Type。 |
| const HiTraceId *id | 实施信息埋点操作的HiTraceId。 |
| const char *fmt | HiTraceMeter打点操作传入的trace说明信息的格式化字符串。 |
OH_HiTrace_InitId()
void OH_HiTrace_InitId(HiTraceId *id)
描述
初始化HiTraceId。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiTraceId *id | 需要初始化的HiTraceId。 |
OH_HiTrace_IdFromBytes()
void OH_HiTrace_IdFromBytes(HiTraceId *id, const uint8_t *pIdArray, int len)
描述
根据字节数组创建HiTraceId。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiTraceId *id | 需要创建的HiTraceId。 |
| const uint8_t *pIdArray | 字节数组。 |
| int len | 字节数组长度。 |
OH_HiTrace_IsIdValid()
bool OH_HiTrace_IsIdValid(const HiTraceId *id)
描述
判断HiTraceId是否有效。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const HiTraceId *id | 需要判断是否有效的HiTraceId。 |
返回：
| 类型 | 说明 |
|---|---|
| bool | true：HiTraceId有效；false：HiTraceId无效。 |
OH_HiTrace_IsFlagEnabled()
bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag)
描述
判断HiTraceId是否启用了跟踪标志flag。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const HiTraceId *id | 需要判断指定跟踪标志是否启用的HiTraceId。 |
| HiTrace_Flag flag | 指定的跟踪标志，见HiTrace_Flag。 |
返回：
| 类型 | 说明 |
|---|---|
| bool | true：HiTraceId已启用flag；false：HiTraceId未启用flag。 |
OH_HiTrace_EnableFlag()
void OH_HiTrace_EnableFlag(const HiTraceId *id, HiTrace_Flag flag)
描述
启用HiTraceId中指定的跟踪标志。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const HiTraceId *id | 需要启用指定跟踪标志的HiTraceId。 |
| HiTrace_Flag flag | 指定的跟踪标志，见HiTrace_Flag。 |
OH_HiTrace_GetFlags()
int OH_HiTrace_GetFlags(const HiTraceId *id)
描述
获取HiTraceId中设置的跟踪标志位。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const HiTraceId *id | 需要获取跟踪标志位的HiTraceId。 |
返回：
| 类型 | 说明 |
|---|---|
| int | HiTraceId中设置的跟踪标志位。 |
OH_HiTrace_SetFlags()
void OH_HiTrace_SetFlags(HiTraceId *id, int flags)
描述
设置跟踪标志位到HiTraceId中。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiTraceId *id | 需要设置跟踪标志位的HiTraceId。 |
| int flags | 指定的跟踪标志位，见HiTrace_Flag。 |
OH_HiTrace_GetChainId()
uint64_t OH_HiTrace_GetChainId(const HiTraceId *id)
描述
获取HiTraceId中的跟踪链ID。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const HiTraceId *id | 需要获取跟踪链ID的HiTraceId。 |
返回：
| 类型 | 说明 |
|---|---|
| uint64_t | 跟踪链ID。 |
OH_HiTrace_SetChainId()
void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId)
描述
设置跟踪链ID到HiTraceId中。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiTraceId *id | 需要设置跟踪链ID的HiTraceId。 |
| uint64_t chainId | 需要设置的跟踪链ID。 |
OH_HiTrace_GetSpanId()
uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id)
描述
获取当前HiTraceId中的分支ID。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const HiTraceId *id | 需要获取分支ID的HiTraceId。 |
返回：
| 类型 | 说明 |
|---|---|
| uint64_t | HiTraceId中设置的分支ID。 |
OH_HiTrace_SetSpanId()
void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId)
描述
设置分支ID到HiTraceId中。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiTraceId *id | 需要设置分支ID的HiTraceId。 |
| uint64_t spanId | 需要设置的分支ID。 |
OH_HiTrace_GetParentSpanId()
uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id)
描述
获取当前HiTraceId中的父分支ID。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const HiTraceId *id | 需要获取父分支ID的HiTraceId。 |
返回：
| 类型 | 说明 |
|---|---|
| uint64_t | HiTraceId中设置的父分支ID。 |
OH_HiTrace_SetParentSpanId()
void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId)
描述
设置HiTraceId结构的parentSpanId字段。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| HiTraceId *id | 需要设置父分支ID的HiTraceId。 |
| uint64_t parentSpanId | 需要设置的父分支ID。 |
OH_HiTrace_IdToBytes()
int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len)
描述
将HiTraceId转换为字节数组，用于缓存或者通信传递。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const HiTraceId* id | 需要转换的HiTraceId。 |
| uint8_t* pIdArray | 字节数组。 |
| int len | 字节数组长度。 |
返回：
| 类型 | 说明 |
|---|---|
| int | 转换后的字节数组长度。 |
OH_HiTrace_StartTrace()
void OH_HiTrace_StartTrace(const char *name)
描述
标记一个同步跟踪耗时任务的开始。
同步跟踪打点接口OH_HiTrace_StartTrace和OH_HiTrace_FinishTrace必须配对使用。
OH_HiTrace_StartTrace和OH_HiTrace_FinishTrace函数对可以嵌套使用，跟踪解析时使用栈式数据结构进行匹配。
从API version 19开始，建议使用OH_HiTrace_StartTraceEx接口，以便分级控制跟踪输出。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| const char *name | 跟踪的名字。 |
OH_HiTrace_FinishTrace()
void OH_HiTrace_FinishTrace(void)
描述
标记一个同步跟踪耗时任务的结束。
必须和OH_HiTrace_StartTrace配对使用。跟踪解析时，和其前执行流程中最近的OH_HiTrace_StartTrace进行匹配。
从API version 19开始，建议使用OH_HiTrace_FinishTraceEx接口，以便分级控制跟踪输出。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 10
OH_HiTrace_StartAsyncTrace()
void OH_HiTrace_StartAsyncTrace(const char *name, int32_t taskId)
描述
标记一个异步跟踪耗时任务的开始。
用于在异步操作前调用进行开始打点，异步跟踪开始和结束数据由于不是顺序发生的，所以解析时需要通过一个唯一的taskId进行识别。
必须和OH_HiTrace_FinishAsyncTrace配对使用，参数name和taskId相同的开始与结束打点相匹配，构成一个异步跟踪耗时任务。
如果有多个相同name的任务需要跟踪或者对同一个任务跟踪多次，并且任务同时被执行，则每次调用的taskId需不相同。
如果具有相同name的任务是串行执行的，则taskId可以相同。
从API version 19开始，建议使用OH_HiTrace_StartAsyncTraceEx接口，以便分级控制跟踪输出与跟踪聚类。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| const char *name | 异步跟踪的名字。 |
| int32_t taskId | 异步跟踪的ID。 异步跟踪开始和结束由于不是顺序发生的，所以需要通过name和每次执行唯一的taskId进行开始和结束的匹配。 |
OH_HiTrace_FinishAsyncTrace()
void OH_HiTrace_FinishAsyncTrace(const char *name, int32_t taskId)
描述
标记一个异步跟踪耗时任务的结束。
在异步操作完成后如回调函数中调用，进行结束打点。
和OH_HiTrace_StartAsyncTrace配对使用，参数name和taskId必须与异步跟踪的开始打点接口的对应参数值保持一致。
从API version 19开始，建议使用OH_HiTrace_FinishAsyncTraceEx接口，以便分级控制跟踪输出。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| const char *name | 异步跟踪的名字。 |
| int32_t taskId | 异步跟踪的ID。异步跟踪开始和结束由于不是顺序发生的，所以需要通过name和每次执行唯一的taskId进行开始和结束的匹配。 |
OH_HiTrace_CountTrace()
void OH_HiTrace_CountTrace(const char *name, int64_t count)
描述
用于跟踪给定整数变量名和整数值。
多次执行该接口可以跟踪给定整数变量在不同时刻的数值变化。
从API version 19开始，建议使用OH_HiTrace_CountTraceEx接口，以便分级控制跟踪输出。
系统能力： SystemCapability.HiviewDFX.HiTrace
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| const char *name | 整数变量跟踪的名字，不必与真实变量名相同。 |
| int64_t count | 整数值。 |
OH_HiTrace_StartTraceEx()
void OH_HiTrace_StartTraceEx(HiTrace_Output_Level level, const char *name, const char *customArgs)
描述
标记一个同步跟踪耗时任务的开始，分级控制跟踪输出。
同步跟踪打点接口OH_HiTrace_StartTraceEx和OH_HiTrace_FinishTraceEx必须配对使用。
OH_HiTrace_StartTraceEx和OH_HiTrace_FinishTraceEx函数对可以嵌套使用，跟踪解析时使用栈式数据结构进行匹配。
起始版本： 19
参数：
| 参数项 | 描述 |
|---|---|
| HiTrace_Output_Level level | 跟踪输出优先级。 |
| const char *name | 同步跟踪的名字。 |
| const char *customArgs | 键值对，多个键值对使用逗号分隔，例"key1=value1,key2=value2"。 |
OH_HiTrace_FinishTraceEx()
void OH_HiTrace_FinishTraceEx(HiTrace_Output_Level level)
描述
标记一个同步跟踪耗时任务的结束，分级控制跟踪输出。
必须和OH_HiTrace_StartTraceEx配对使用，参数level必须与同步跟踪的开始打点接口OH_HiTrace_StartTraceEx的对应参数值一致。
跟踪数据解析时，和其前执行流程中最近的OH_HiTrace_StartTraceEx进行匹配。
起始版本： 19
参数：
| 参数项 | 描述 |
|---|---|
| HiTrace_Output_Level level | 跟踪输出优先级。 |
OH_HiTrace_StartAsyncTraceEx()
void OH_HiTrace_StartAsyncTraceEx(HiTrace_Output_Level level, const char *name, int32_t taskId, const char *customCategory, const char *customArgs)
描述
标记一个异步跟踪耗时任务的开始，分级控制跟踪输出。
用于在异步操作执行前进行开始打点，异步跟踪开始和结束数据由于不是顺序发生的，所以解析时需要通过一个唯一的taskId进行识别。
和OH_HiTrace_FinishAsyncTraceEx配对使用，参数name和taskId相同的开始与结束打点相匹配，构成一个异步跟踪耗时任务。
如果有多个相同name的任务需要跟踪或者对同一个任务跟踪多次，并且任务同时被执行，则每次调用的taskId需不相同。
如果具有相同name的任务是串行执行的，则taskId可以相同。
不同进程的taskId不会相互干扰。
起始版本： 19
参数：
| 参数项 | 描述 |
|---|---|
| HiTrace_Output_Level level | 跟踪输出优先级。 |
| const char *name | 异步跟踪的名字。 |
| int32_t taskId | 异步跟踪的ID。 |
| const char *customCategory | 自定义聚类名称，用于聚合同一类异步跟踪打点。 |
| const char *customArgs | 键值对，多个键值对使用逗号分隔，例"key1=value1,key2=value2"。 |
OH_HiTrace_FinishAsyncTraceEx()
void OH_HiTrace_FinishAsyncTraceEx(HiTrace_Output_Level level, const char *name, int32_t taskId)
描述
标记一个异步跟踪耗时任务的结束，分级控制跟踪输出。
用于在异步操作完成后进行结束打点，例如在回调函数中调用。
和OH_HiTrace_StartAsyncTraceEx配对使用，参数level、name和taskId必须与异步跟踪开始打点接口的对应参数值保持一致。
起始版本： 19
参数：
| 参数项 | 描述 |
|---|---|
| HiTrace_Output_Level level | 跟踪输出优先级。 |
| const char *name | 异步跟踪的名字。 |
| int32_t taskId | 异步跟踪的ID。 |
OH_HiTrace_CountTraceEx()
void OH_HiTrace_CountTraceEx(HiTrace_Output_Level level, const char *name, int64_t count)
描述
标记一个跟踪的整数变量，分级控制跟踪输出。
起始版本： 19
参数：
| 参数项 | 描述 |
|---|---|
| HiTrace_Output_Level level | 跟踪输出优先级。 |
| const char *name | 整数变量的名称，不必与实际变量名相同。 |
| int64_t count | 整数值。 |
OH_HiTrace_IsTraceEnabled()
bool OH_HiTrace_IsTraceEnabled(void)
描述
判断当前是否开启应用trace捕获。
起始版本： 19
返回：
| 类型 | 说明 |
|---|---|
| bool | 使用hitrace命令行工具等方式开启采集时返回true。 未开启采集或停止采集后返回false，此时调用HiTraceMeter性能跟踪打点接口无效。 |
OH_HiTrace_RegisterTraceListener()
int32_t OH_HiTrace_RegisterTraceListener(OH_HiTrace_TraceEventListener callback)
描述
注册应用trace捕获开关通知回调，使用callback异步回调。
注册成功后，立即执行一次回调函数，后续回调函数由应用trace捕获开关状态变化触发执行。
回调函数保存在应用进程内，一个进程最多可以注册10个回调函数。
若注册的回调包含耗时操作，当回调被执行时，注册或注销行为会被阻塞（等待回调执行完成）。
因此，建议不要在应用主线程中注册或注销包含耗时操作的回调，避免发生应用冻屏。
起始版本： 22
参数：
| 参数项 | 描述 |
|---|---|
| OH_HiTrace_TraceEventListener callback | 注册的回调函数。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | 回调注册状态。 >= 0：注册成功，返回用于注销的回调索引，索引范围0到9； -1：已达到最大回调函数注册数量； -2：无效参数，参数非OH_HiTrace_TraceEventListener类型。 |
OH_HiTrace_UnregisterTraceListener()
int32_t OH_HiTrace_UnregisterTraceListener(int32_t index)
描述
注销应用trace捕获开关通知回调。
使用OH_HiTrace_RegisterTraceListener返回的回调索引，注销该索引关联的回调函数。
起始版本： 22
参数：
| 参数项 | 描述 |
|---|---|
| int32_t index | 已注册回调函数索引。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | 回调注销状态。 0：注销成功； -1：目标索引的回调函数未注册； -2：无效索引，参数index值不在0到9的范围内。 |