1# trace.h 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @qq_437963121--> 6<!--Designer: @kutcherzhou1; @MontSaintMichel--> 7<!--Tester: @gcw_KuLfPSbe--> 8<!--Adviser: @foryourself--> 9 10## 概述 11 12HiTraceMeter和HitraceChain模块打点接口定义，通过这些接口实现性能打点和分布式跟踪功能。<br> 用户态tarce格式使用竖线字符作为分隔符，所以通过HiTraceMeter接口传递的字符串类型参数应避免包含该字符，防止trace解析异常。<br> 用户态trace总长度限制512字符，超过的部分将会被截断。 13 14**引用文件：** <hitrace/trace.h> 15 16**库：** libhitrace_ndk.z.so 17 18**系统能力：** SystemCapability.HiviewDFX.HiTrace 19 20**起始版本：** 10 21 22**相关模块：** [Hitrace](capi-hitrace.md) 23 24## 汇总 25 26### 结构体 27 28| 名称 | typedef关键字 | 描述 | 29| -- | -- | -- | 30| [HiTraceId](capi-hitrace-hitraceid.md) | HiTraceId | HiTraceId定义。 | 31 32### 枚举 33 34| 名称 | typedef关键字 | 描述 | 35| -- | -- | -- | 36| [HiTraceId_Valid](#hitraceid_valid) | HiTraceId_Valid | HiTraceId是否有效标志。 | 37| [HiTrace_Version](#hitrace_version) | HiTrace_Version | HiTrace版本号。 | 38| [HiTrace_Flag](#hitrace_flag) | HiTrace_Flag | HiTrace跟踪标志。 | 39| [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type) | HiTrace_Tracepoint_Type | 跟踪埋点类型枚举。 | 40| [HiTrace_Communication_Mode](#hitrace_communication_mode) | HiTrace_Communication_Mode | 跟踪通信类型枚举。 | 41| [HiTrace_Output_Level](#hitrace_output_level) | HiTrace_Output_Level | HiTrace输出级别。低于系统跟踪输出级别阈值的打点将不会生效。log版本阈值为HITRACE_LEVEL_INFO；nolog版本阈值为HITRACE_LEVEL_COMMERCIAL。 | 42 43### 函数 44 45| 名称 | 描述 | 46| -- | -- | 47| [HiTraceId OH_HiTrace_BeginChain(const char *name, int flags)](#oh_hitrace_beginchain) | 开始跟踪。<br> 当前线程TLS（Thread Local Storage，线程本地存储）中不存在有效的HiTraceId时，生成有效的HiTraceId并设置到当前线程TLS中，返回该HiTraceId。<br> 当前线程TLS中已存在有效的HiTraceId时，不会开始新的跟踪，返回各属性值均为0的无效HiTraceId。<br> | 48| [void OH_HiTrace_EndChain()](#oh_hitrace_endchain) | 结束跟踪。<br> 结束跟踪并将当前线程TLS中的HiTraceId设置为无效。<br> | 49| [HiTraceId OH_HiTrace_GetId()](#oh_hitrace_getid) | 获取跟踪标识。<br> 获取当前线程TLS中的HiTraceId。<br> | 50| [void OH_HiTrace_SetId(const HiTraceId *id)](#oh_hitrace_setid) | 设置跟踪标识。<br> 将给定的HiTraceId设置到当前线程TLS中。若给定的HiTraceId无效，则不执行任何操作。<br> | 51| [void OH_HiTrace_ClearId(void)](#oh_hitrace_clearid) | 清除跟踪标识。<br> 将当前线程TLS中的HiTraceId设置为无效。<br> | 52| [HiTraceId OH_HiTrace_CreateSpan(void)](#oh_hitrace_createspan) | 创建跟踪分支。<br> 创建一个HiTraceId，使用当前线程TLS中的chainId、spanId初始化HiTraceId的chainId、parentSpanId，并为HiTraceId生成一个新的spanId，返回该HiTraceId。<br> | 53| [void OH_HiTrace_Tracepoint(HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId *id, const char *fmt, ...)](#oh_hitrace_tracepoint) | HiTraceMeter跟踪信息埋点。<br>type为客户端发送CS和服务端接收SC时，进行同步HiTraceMeter开始打点；<br>type为客户端接收CC和服务端发送SS时，进行同步HiTraceMeter结束打点；<br>type为通用类型GENERAL时，不会进行HiTraceMeter打点。<br>type为客户端发送CS和客户端接收CC的信息埋点需配套使用；<br>type为服务端接收SC和服务端发送SS的信息埋点需配套使用。<br>否则，HiTraceMeter开始与结束打点无法正常匹配。 | 54| [void OH_HiTrace_InitId(HiTraceId *id)](#oh_hitrace_initid) | 初始化HiTraceId。 | 55| [void OH_HiTrace_IdFromBytes(HiTraceId *id, const uint8_t *pIdArray, int len)](#oh_hitrace_idfrombytes) | 根据字节数组创建HiTraceId。 | 56| [bool OH_HiTrace_IsIdValid(const HiTraceId *id)](#oh_hitrace_isidvalid) | 判断HiTraceId是否有效。 | 57| [bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag)](#oh_hitrace_isflagenabled) | 判断HiTraceId是否启用了跟踪标志flag。 | 58| [void OH_HiTrace_EnableFlag(const HiTraceId *id, HiTrace_Flag flag)](#oh_hitrace_enableflag) | 启用HiTraceId中指定的跟踪标志。 | 59| [int OH_HiTrace_GetFlags(const HiTraceId *id)](#oh_hitrace_getflags) | 获取HiTraceId中设置的跟踪标志位。 | 60| [void OH_HiTrace_SetFlags(HiTraceId *id, int flags)](#oh_hitrace_setflags) | 设置跟踪标志位到[HiTraceId](capi-hitrace-hitraceid.md)中。 | 61| [uint64_t OH_HiTrace_GetChainId(const HiTraceId *id)](#oh_hitrace_getchainid) | 获取HiTraceId中的跟踪链ID。 | 62| [void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId)](#oh_hitrace_setchainid) | 设置跟踪链ID到HiTraceId中。 | 63| [uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id)](#oh_hitrace_getspanid) | 获取当前HiTraceId中的分支ID。 | 64| [void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId)](#oh_hitrace_setspanid) | 设置分支ID到HiTraceId中。 | 65| [uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id)](#oh_hitrace_getparentspanid) | 获取当前HiTraceId中的父分支ID。 | 66| [void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId)](#oh_hitrace_setparentspanid) | 设置HiTraceId结构的parentSpanId字符。 | 67| [int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len)](#oh_hitrace_idtobytes) | 将HiTraceId转换为字节数组，用于缓存或者通信传递。 | 68| [void OH_HiTrace_StartTrace(const char *name)](#oh_hitrace_starttrace) | 标记一个同步跟踪耗时任务的开始。<br> 同步跟踪打点接口OH_HiTrace_StartTrace()和OH_HiTrace_FinishTrace()必须配对使用。<br> OH_HiTrace_StartTrace()和OH_HiTrace_FinishTrace()函数对可以嵌套使用，跟踪解析时使用栈式数据结构进行匹配。<br> 从API version 19开始，建议使用OH_HiTrace_StartTraceEx()接口，以便分级控制跟踪输出。<br> | 69| [void OH_HiTrace_FinishTrace(void)](#oh_hitrace_finishtrace) | 标记一个同步跟踪耗时任务的结束。<br> 必须和OH_HiTrace_StartTrace()配对使用。跟踪解析时，和其前执行流程中最近的OH_HiTrace_StartTrace()进行匹配。<br> 从API version 19开始，建议使用OH_HiTrace_FinishTraceEx()接口，以便分级控制跟踪输出。<br> | 70| [void OH_HiTrace_StartAsyncTrace(const char *name, int32_t taskId)](#oh_hitrace_startasynctrace) | 标记一个异步跟踪耗时任务的开始。<br> 用于在异步操作前调用进行开始打点，异步跟踪开始和结束数据由于不是顺序发生的，所以解析时需要通过一个唯一的taskId进行识别。<br> 必须和OH_HiTrace_FinishAsyncTrace()配对使用，参数name和taskId相同的开始与结束打点相匹配，构成一个异步跟踪耗时任务。<br> 如果有多个相同name的任务需要跟踪或者对同一个任务跟踪多次，并且任务同时被执行，则每次调用的taskId需不相同。<br> 如果具有相同name的任务是串行执行的，则taskId可以相同。<br> 从API version 19开始，建议使用OH_HiTrace_StartAsyncTraceEx()接口，以便分级控制跟踪输出与跟踪聚类。<br> | 71| [void OH_HiTrace_FinishAsyncTrace(const char *name, int32_t taskId)](#oh_hitrace_finishasynctrace) | 标记一个异步跟踪耗时任务的结束。<br> 在异步操作完成后如回调函数中调用，进行结束打点。<br> 和OH_HiTrace_StartAsyncTrace()配对使用，参数name和taskId必须与异步跟踪的开始打点接口的对应参数值保持一致。<br> 从API version 19开始，建议使用OH_HiTrace_FinishAsyncTraceEx()接口，以便分级控制跟踪输出。<br> | 72| [void OH_HiTrace_CountTrace(const char *name, int64_t count)](#oh_hitrace_counttrace) | 用于跟踪给定整数变量名和整数值。<br> 多次执行该接口可以跟踪给定整数变量在不同时刻的数值变化。<br> 从API version 19开始，建议使用OH_HiTrace_CountTraceEx()接口，以便分级控制跟踪输出。<br> | 73| [void OH_HiTrace_StartTraceEx(HiTrace_Output_Level level, const char *name, const char *customArgs)](#oh_hitrace_starttraceex) | 标记一个同步跟踪耗时任务的开始，分级控制跟踪输出。<br> 同步跟踪打点接口OH_HiTrace_StartTraceEx()和OH_HiTrace_FinishTraceEx()必须配对使用。<br> OH_HiTrace_StartTraceEx()和OH_HiTrace_FinishTraceEx()函数对可以嵌套使用，跟踪解析时使用栈式数据结构进行匹配。<br> | 74| [void OH_HiTrace_FinishTraceEx(HiTrace_Output_Level level)](#oh_hitrace_finishtraceex) | 标记一个同步跟踪耗时任务的结束，分级控制跟踪输出。<br> 必须和OH_HiTrace_StartTraceEx()配对使用，参数level必须与同步跟踪的开始打点接口OH_HiTrace_StartTraceEx()的对应参数值一致。<br> 跟踪数据解析时，和其前执行流程中最近的OH_HiTrace_StartTraceEx()进行匹配。<br> | 75| [void OH_HiTrace_StartAsyncTraceEx(HiTrace_Output_Level level, const char *name, int32_t taskId, const char *customCategory, const char *customArgs)](#oh_hitrace_startasynctraceex) | 标记一个异步跟踪耗时任务的开始，分级控制跟踪输出。<br> 用于在异步操作执行前进行开始打点，异步跟踪开始和结束数据由于不是顺序发生的，所以解析时需要通过一个唯一的taskId进行识别。<br> 和OH_HiTrace_FinishAsyncTraceEx()配对使用，参数name和taskId相同的开始与结束打点相匹配，构成一个异步跟踪耗时任务。<br> 如果有多个相同name的任务需要跟踪或者对同一个任务跟踪多次，并且任务同时被执行，则每次调用的taskId需不相同。<br> 如果具有相同name的任务是串行执行的，则taskId可以相同。<br> 不同进程的taskId不会相互干扰。<br> | 76| [void OH_HiTrace_FinishAsyncTraceEx(HiTrace_Output_Level level, const char *name, int32_t taskId)](#oh_hitrace_finishasynctraceex) | 标记一个异步跟踪耗时任务的结束，分级控制跟踪输出。<br> 用于在异步操作完成后进行结束打点，例如在回调函数中调用。<br> 和OH_HiTrace_StartAsyncTraceEx()配对使用，参数level、name和taskId必须与异步跟踪开始打点接口的对应参数值保持一致。<br> | 77| [void OH_HiTrace_CountTraceEx(HiTrace_Output_Level level, const char *name, int64_t count)](#oh_hitrace_counttraceex) | 标记一个跟踪的整数变量，分级控制跟踪输出。 | 78| [bool OH_HiTrace_IsTraceEnabled(void)](#oh_hitrace_istraceenabled) | 判断当前是否开启应用trace捕获。 | 79 80## 枚举类型说明 81 82### HiTraceId_Valid 83 84``` 85enum HiTraceId_Valid 86``` 87 88**描述** 89 90HiTraceId是否有效标志。 91 92**系统能力：** SystemCapability.HiviewDFX.HiTrace 93 94**起始版本：** 12 95 96| 枚举项 | 描述 | 97| -- | -- | 98| HITRACE_ID_INVALID = 0 | 无效HiTraceId。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 99| HITRACE_ID_VALID = 1 | 有效HiTraceId。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 100 101### HiTrace_Version 102 103``` 104enum HiTrace_Version 105``` 106 107**描述** 108 109HiTrace版本号。 110 111**系统能力：** SystemCapability.HiviewDFX.HiTrace 112 113**起始版本：** 12 114 115| 枚举项 | 描述 | 116| -- | -- | 117| HITRACE_VER_1 = 0 | 版本1。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 118 119### HiTrace_Flag 120 121``` 122enum HiTrace_Flag 123``` 124 125**描述** 126 127HiTrace跟踪标志。 128 129**系统能力：** SystemCapability.HiviewDFX.HiTrace 130 131**起始版本：** 12 132 133| 枚举项 | 描述 | 134| -- | -- | 135| HITRACE_FLAG_DEFAULT = 0 | 缺省标志。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 136| HITRACE_FLAG_INCLUDE_ASYNC = 1 << 0 | 异步调用标志。<br> 设置该标志，同时跟踪同步和异步调用；缺省只跟踪同步调用。<br><br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 137| HITRACE_FLAG_DONOT_CREATE_SPAN = 1 << 1 | 无分支标志。<br> 设置该标志，不创建分支信息；缺省创建分支信息。<br><br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 138| HITRACE_FLAG_TP_INFO = 1 << 2 | 埋点标志。<br> 调试场景下设置该标志，调用信息埋点接口OH_HiTrace_Tracepoint()时，会打印埋点信息hilog日志；缺省不打印埋点信息hilog日志。<br><br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 139| HITRACE_FLAG_NO_BE_INFO = 1 << 3 | 无开始结束信息标志。<br> 调试场景下设置该标志，调用开始跟踪接口OH_HiTrace_BeginChain()和结束跟踪接口OH_HiTrace_EndChain()时，分别会打印开始、结束跟踪信息hilog日志；缺省不打印开始、结束跟踪信息hilog日志。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 140| HITRACE_FLAG_DONOT_ENABLE_LOG = 1 << 4 | 日志关联标志。<br> 设置该标志，不会在hilog日志中附加HiTraceId信息；缺省会在hilog日志中附加HiTraceId信息。<br><br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 141| HITRACE_FLAG_FAULT_TRIGGER = 1 << 5 | 故障触发标志。预置标志，暂未启用。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 142| HITRACE_FLAG_D2D_TP_INFO = 1 << 6 | 设备间埋点标志。HITRACE_FLAG_TP_INFO的一个子集，调试场景下使用。<br> 当已设置HITRACE_FLAG_TP_INFO标志时，HITRACE_FLAG_D2D_TP_INFO标志不生效；<br> 当未设置HITRACE_FLAG_TP_INFO标志时，设置HITRACE_FLAG_D2D_TP_INFO标志，此时调用信息埋点接口OH_HiTrace_Tracepoint()，仅当mode参数为设备间通信HITRACE_CM_DEVICE的情况下，会打印埋点信息hilog日志。<br><br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 143 144### HiTrace_Tracepoint_Type 145 146``` 147enum HiTrace_Tracepoint_Type 148``` 149 150**描述** 151 152跟踪埋点类型枚举。 153 154**系统能力：** SystemCapability.HiviewDFX.HiTrace 155 156**起始版本：** 12 157 158| 枚举项 | 描述 | 159| -- | -- | 160| HITRACE_TP_CS = 0 | 客户端发送。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 161| HITRACE_TP_CR = 1 | 客户端接收。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 162| HITRACE_TP_SS = 2 | 服务端发送。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 163| HITRACE_TP_SR = 3 | 服务端接收。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 164| HITRACE_TP_GENERAL = 4 | 通用类型，标识HITRACE_TP_CS、HITRACE_TP_CR、HITRACE_TP_SS、HITRACE_TP_SR四种场景之外的埋点。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 165 166### HiTrace_Communication_Mode 167 168``` 169enum HiTrace_Communication_Mode 170``` 171 172**描述** 173 174跟踪通信类型枚举。 175 176**系统能力：** SystemCapability.HiviewDFX.HiTrace 177 178**起始版本：** 12 179 180| 枚举项 | 描述 | 181| -- | -- | 182| HITRACE_CM_DEFAULT = 0 | 缺省通信类型。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 183| HITRACE_CM_THREAD = 1 | 线程间通信。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 184| HITRACE_CM_PROCESS = 2 | 进程间通信。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 185| HITRACE_CM_DEVICE = 3 | 设备间通信。<br>**起始版本：** 12<br>**系统能力：** SystemCapability.HiviewDFX.HiTrace | 186 187### HiTrace_Output_Level 188 189``` 190enum HiTrace_Output_Level 191``` 192 193**描述** 194 195HiTrace输出级别。低于系统跟踪输出级别阈值的打点将不会生效。log版本阈值为HITRACE_LEVEL_INFO；nolog版本阈值为HITRACE_LEVEL_COMMERCIAL。 196 197**系统能力：** SystemCapability.HiviewDFX.HiTrace 198 199**起始版本：** 19 200 201| 枚举项 | 描述 | 202| -- | -- | 203| HITRACE_LEVEL_DEBUG = 0 | 仅用于调试的输出级别，优先级最低。<br>**起始版本：** 19 | 204| HITRACE_LEVEL_INFO = 1 | 用于log版本的输出级别。<br>**起始版本：** 19 | 205| HITRACE_LEVEL_CRITICAL = 2 | 用于log版本的输出级别，优先级高于HITRACE_LEVEL_INFO。<br>**起始版本：** 19 | 206| HITRACE_LEVEL_COMMERCIAL = 3 | 用于nolog版本的输出级别，优先级最高。<br>**起始版本：** 19 | 207| HITRACE_LEVEL_MAX = HITRACE_LEVEL_COMMERCIAL | 输出级别范围限制。<br>**起始版本：** 19 | 208 209 210## 函数说明 211 212### OH_HiTrace_BeginChain() 213 214``` 215HiTraceId OH_HiTrace_BeginChain(const char *name, int flags) 216``` 217 218**描述** 219 220开始跟踪。<br> 当前线程TLS（Thread Local Storage，线程本地存储）中不存在有效的HiTraceId时，生成有效的HiTraceId并设置到当前线程TLS中，返回该HiTraceId。<br> 当前线程TLS中已存在有效的HiTraceId时，不会开始新的跟踪，返回各属性值均为0的无效HiTraceId。<br> 221 222**系统能力：** SystemCapability.HiviewDFX.HiTrace 223 224**起始版本：** 12 225 226 227**参数：** 228 229| 参数项 | 描述 | 230| -- | -- | 231| const char *name | 跟踪业务名。 | 232| int flags | 跟踪标志组合，见[HiTrace_Flag](capi-trace-h.md#hitrace_flag)。 | 233 234**返回：** 235 236| 类型 | 说明 | 237| -- | -- | 238| [HiTraceId](capi-hitrace-hitraceid.md) | [HiTraceId](capi-hitrace-hitraceid.md)结构体。 | 239 240### OH_HiTrace_EndChain() 241 242``` 243void OH_HiTrace_EndChain() 244``` 245 246**描述** 247 248结束跟踪。<br> 结束跟踪并将当前线程TLS中的HiTraceId设置为无效。<br> 249 250**系统能力：** SystemCapability.HiviewDFX.HiTrace 251 252**起始版本：** 12 253 254### OH_HiTrace_GetId() 255 256``` 257HiTraceId OH_HiTrace_GetId() 258``` 259 260**描述** 261 262获取跟踪标识。<br> 获取当前线程TLS中的HiTraceId。<br> 263 264**系统能力：** SystemCapability.HiviewDFX.HiTrace 265 266**起始版本：** 12 267 268**返回：** 269 270| 类型 | 说明 | 271| -- | -- | 272| [HiTraceId](capi-hitrace-hitraceid.md) | [HiTraceId](capi-hitrace-hitraceid.md)结构体。 | 273 274### OH_HiTrace_SetId() 275 276``` 277void OH_HiTrace_SetId(const HiTraceId *id) 278``` 279 280**描述** 281 282设置跟踪标识。<br> 将给定的HiTraceId设置到当前线程TLS中。若给定的HiTraceId无效，则不执行任何操作。<br> 283 284**系统能力：** SystemCapability.HiviewDFX.HiTrace 285 286**起始版本：** 12 287 288 289**参数：** 290 291| 参数项 | 描述 | 292| -- | -- | 293| [const HiTraceId](capi-hitrace-hitraceid.md) *id | 要设置的[HiTraceId](capi-hitrace-hitraceid.md)。 | 294 295### OH_HiTrace_ClearId() 296 297``` 298void OH_HiTrace_ClearId(void) 299``` 300 301**描述** 302 303清除跟踪标识。<br> 将当前线程TLS中的HiTraceId设置为无效。<br> 304 305**系统能力：** SystemCapability.HiviewDFX.HiTrace 306 307**起始版本：** 12 308 309### OH_HiTrace_CreateSpan() 310 311``` 312HiTraceId OH_HiTrace_CreateSpan(void) 313``` 314 315**描述** 316 317创建跟踪分支。<br> 创建一个HiTraceId，使用当前线程TLS中的chainId、spanId初始化HiTraceId的chainId、parentSpanId，并为HiTraceId生成一个新的spanId，返回该HiTraceId。<br> 318 319**系统能力：** SystemCapability.HiviewDFX.HiTrace 320 321**起始版本：** 12 322 323**返回：** 324 325| 类型 | 说明 | 326| -- | -- | 327| [HiTraceId](capi-hitrace-hitraceid.md) | [HiTraceId](capi-hitrace-hitraceid.md)结构体。 | 328 329### OH_HiTrace_Tracepoint() 330 331``` 332void OH_HiTrace_Tracepoint(HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId *id, const char *fmt, ...) 333``` 334 335**描述** 336 337HiTraceMeter跟踪信息埋点。<br>type为客户端发送CS和服务端接收SC时，进行同步HiTraceMeter开始打点；<br>type为客户端接收CC和服务端发送SS时，进行同步HiTraceMeter结束打点；<br>type为通用类型GENERAL时，不会进行HiTraceMeter打点。<br>type为客户端发送CS和客户端接收CC的信息埋点需配套使用；<br>type为服务端接收SC和服务端发送SS的信息埋点需配套使用。<br>否则，HiTraceMeter开始与结束打点无法正常匹配。 338 339**系统能力：** SystemCapability.HiviewDFX.HiTrace 340 341**起始版本：** 12 342 343 344**参数：** 345 346| 参数项 | 描述 | 347| -- | -- | 348| [HiTrace_Communication_Mode](capi-trace-h.md#hitrace_communication_mode) mode | 跟踪通信模式，见[HiTrace_Communication_Mode](capi-trace-h.md#hitrace_communication_mode)。 | 349| [HiTrace_Tracepoint_Type](capi-trace-h.md#hitrace_tracepoint_type) type | 跟踪信息类型，见[HiTrace_Tracepoint_Type](capi-trace-h.md#hitrace_tracepoint_type)。 | 350| [const HiTraceId](capi-hitrace-hitraceid.md) *id | 实施信息埋点操作的[HiTraceId](capi-hitrace-hitraceid.md)。 | 351| const char *fmt | HiTraceMeter打点操作传入的trace说明信息的格式化字符串。 | 352 353### OH_HiTrace_InitId() 354 355``` 356void OH_HiTrace_InitId(HiTraceId *id) 357``` 358 359**描述** 360 361初始化HiTraceId。 362 363**系统能力：** SystemCapability.HiviewDFX.HiTrace 364 365**起始版本：** 12 366 367 368**参数：** 369 370| 参数项 | 描述 | 371| -- | -- | 372| [HiTraceId](capi-hitrace-hitraceid.md) *id | 需要初始化的[HiTraceId](capi-hitrace-hitraceid.md)。 | 373 374### OH_HiTrace_IdFromBytes() 375 376``` 377void OH_HiTrace_IdFromBytes(HiTraceId *id, const uint8_t *pIdArray, int len) 378``` 379 380**描述** 381 382根据字节数组创建HiTraceId。 383 384**系统能力：** SystemCapability.HiviewDFX.HiTrace 385 386**起始版本：** 12 387 388 389**参数：** 390 391| 参数项 | 描述 | 392| -- | -- | 393| [HiTraceId](capi-hitrace-hitraceid.md) *id | 需要创建的[HiTraceId](capi-hitrace-hitraceid.md)。 | 394| const uint8_t *pIdArray | 字节数组。 | 395| int len | 字节数组长度。 | 396 397### OH_HiTrace_IsIdValid() 398 399``` 400bool OH_HiTrace_IsIdValid(const HiTraceId *id) 401``` 402 403**描述** 404 405判断HiTraceId是否有效。 406 407**系统能力：** SystemCapability.HiviewDFX.HiTrace 408 409**起始版本：** 12 410 411 412**参数：** 413 414| 参数项 | 描述 | 415| -- | -- | 416| [const HiTraceId](capi-hitrace-hitraceid.md) *id | 需要判断是否有效的[HiTraceId](capi-hitrace-hitraceid.md)。 | 417 418**返回：** 419 420| 类型 | 说明 | 421| -- | -- | 422| bool | true：[HiTraceId](capi-hitrace-hitraceid.md)有效；false：[HiTraceId](capi-hitrace-hitraceid.md)无效。 | 423 424### OH_HiTrace_IsFlagEnabled() 425 426``` 427bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag) 428``` 429 430**描述** 431 432判断HiTraceId是否启用了跟踪标志flag。 433 434**系统能力：** SystemCapability.HiviewDFX.HiTrace 435 436**起始版本：** 12 437 438 439**参数：** 440 441| 参数项 | 描述 | 442| -- | -- | 443| [const HiTraceId](capi-hitrace-hitraceid.md) *id | 需要判断指定跟踪标志是否启用的[HiTraceId](capi-hitrace-hitraceid.md)。 | 444| [HiTrace_Flag](capi-trace-h.md#hitrace_flag) flag | 指定的跟踪标志，见[HiTrace_Flag](capi-trace-h.md#hitrace_flag)。 | 445 446**返回：** 447 448| 类型 | 说明 | 449| -- | -- | 450| bool | true：[HiTraceId](capi-hitrace-hitraceid.md)已启用flag；false：[HiTraceId](capi-hitrace-hitraceid.md)未启用flag。 | 451 452### OH_HiTrace_EnableFlag() 453 454``` 455void OH_HiTrace_EnableFlag(const HiTraceId *id, HiTrace_Flag flag) 456``` 457 458**描述** 459 460启用HiTraceId中指定的跟踪标志。 461 462**系统能力：** SystemCapability.HiviewDFX.HiTrace 463 464**起始版本：** 12 465 466 467**参数：** 468 469| 参数项 | 描述 | 470| -- | -- | 471| [const HiTraceId](capi-hitrace-hitraceid.md) *id | 需要启用指定跟踪标志的[HiTraceId](capi-hitrace-hitraceid.md)。 | 472| [HiTrace_Flag](capi-trace-h.md#hitrace_flag) flag | 指定的跟踪标志，见[HiTrace_Flag](capi-trace-h.md#hitrace_flag)。 | 473 474### OH_HiTrace_GetFlags() 475 476``` 477int OH_HiTrace_GetFlags(const HiTraceId *id) 478``` 479 480**描述** 481 482获取HiTraceId中设置的跟踪标志位。 483 484**系统能力：** SystemCapability.HiviewDFX.HiTrace 485 486**起始版本：** 12 487 488 489**参数：** 490 491| 参数项 | 描述 | 492| -- | -- | 493| [const HiTraceId](capi-hitrace-hitraceid.md) *id | 需要获取跟踪标志位的[HiTraceId](capi-hitrace-hitraceid.md)。 | 494 495**返回：** 496 497| 类型 | 说明 | 498| -- | -- | 499| int | [HiTraceId](capi-hitrace-hitraceid.md)中设置的跟踪标志位。 | 500 501### OH_HiTrace_SetFlags() 502 503``` 504void OH_HiTrace_SetFlags(HiTraceId *id, int flags) 505``` 506 507**描述** 508 509设置跟踪标志位到[HiTraceId](capi-hitrace-hitraceid.md)中。 510 511**系统能力：** SystemCapability.HiviewDFX.HiTrace 512 513**起始版本：** 12 514 515 516**参数：** 517 518| 参数项 | 描述 | 519| -- | -- | 520| [HiTraceId](capi-hitrace-hitraceid.md) *id | 需要设置跟踪标志位的[HiTraceId](capi-hitrace-hitraceid.md)。 | 521| int flags | 指定的跟踪标志位，见[HiTrace_Flag](capi-trace-h.md#hitrace_flag)。 | 522 523### OH_HiTrace_GetChainId() 524 525``` 526uint64_t OH_HiTrace_GetChainId(const HiTraceId *id) 527``` 528 529**描述** 530 531获取HiTraceId中的跟踪链ID。 532 533**系统能力：** SystemCapability.HiviewDFX.HiTrace 534 535**起始版本：** 12 536 537 538**参数：** 539 540| 参数项 | 描述 | 541| -- | -- | 542| [const HiTraceId](capi-hitrace-hitraceid.md) *id | 需要获取跟踪链ID的[HiTraceId](capi-hitrace-hitraceid.md)。 | 543 544**返回：** 545 546| 类型 | 说明 | 547| -- | -- | 548| uint64_t | 跟踪链ID。 | 549 550### OH_HiTrace_SetChainId() 551 552``` 553void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId) 554``` 555 556**描述** 557 558设置跟踪链ID到HiTraceId中。 559 560**系统能力：** SystemCapability.HiviewDFX.HiTrace 561 562**起始版本：** 12 563 564 565**参数：** 566 567| 参数项 | 描述 | 568| -- | -- | 569| [HiTraceId](capi-hitrace-hitraceid.md) *id | 需要设置跟踪链ID的[HiTraceId](capi-hitrace-hitraceid.md)。 | 570| uint64_t chainId | 需要设置的跟踪链ID。 | 571 572### OH_HiTrace_GetSpanId() 573 574``` 575uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id) 576``` 577 578**描述** 579 580获取当前HiTraceId中的分支ID。 581 582**系统能力：** SystemCapability.HiviewDFX.HiTrace 583 584**起始版本：** 12 585 586 587**参数：** 588 589| 参数项 | 描述 | 590| -- | -- | 591| [const HiTraceId](capi-hitrace-hitraceid.md) *id | 需要获取分支ID的[HiTraceId](capi-hitrace-hitraceid.md)。 | 592 593**返回：** 594 595| 类型 | 说明 | 596| -- | -- | 597| uint64_t | [HiTraceId](capi-hitrace-hitraceid.md)中设置的分支ID。 | 598 599### OH_HiTrace_SetSpanId() 600 601``` 602void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId) 603``` 604 605**描述** 606 607设置分支ID到HiTraceId中。 608 609**系统能力：** SystemCapability.HiviewDFX.HiTrace 610 611**起始版本：** 12 612 613 614**参数：** 615 616| 参数项 | 描述 | 617| -- | -- | 618| [HiTraceId](capi-hitrace-hitraceid.md) *id | 需要设置分支ID的[HiTraceId](capi-hitrace-hitraceid.md)。 | 619| uint64_t spanId | 需要设置的分支ID。 | 620 621### OH_HiTrace_GetParentSpanId() 622 623``` 624uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id) 625``` 626 627**描述** 628 629获取当前HiTraceId中的父分支ID。 630 631**系统能力：** SystemCapability.HiviewDFX.HiTrace 632 633**起始版本：** 12 634 635 636**参数：** 637 638| 参数项 | 描述 | 639| -- | -- | 640| [const HiTraceId](capi-hitrace-hitraceid.md) *id | 需要获取父分支ID的[HiTraceId](capi-hitrace-hitraceid.md)。 | 641 642**返回：** 643 644| 类型 | 说明 | 645| -- | -- | 646| uint64_t | [HiTraceId](capi-hitrace-hitraceid.md)中设置的父分支ID。 | 647 648### OH_HiTrace_SetParentSpanId() 649 650``` 651void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId) 652``` 653 654**描述** 655 656设置HiTraceId结构的parentSpanId字符。 657 658**系统能力：** SystemCapability.HiviewDFX.HiTrace 659 660**起始版本：** 12 661 662 663**参数：** 664 665| 参数项 | 描述 | 666| -- | -- | 667| [HiTraceId](capi-hitrace-hitraceid.md) *id | 需要设置父分支ID的[HiTraceId](capi-hitrace-hitraceid.md)。 | 668| uint64_t parentSpanId | 需要设置的父分支ID。 | 669 670### OH_HiTrace_IdToBytes() 671 672``` 673int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len) 674``` 675 676**描述** 677 678将HiTraceId转换为字节数组，用于缓存或者通信传递。 679 680**系统能力：** SystemCapability.HiviewDFX.HiTrace 681 682**起始版本：** 12 683 684 685**参数：** 686 687| 参数项 | 描述 | 688| -- | -- | 689| [const HiTraceId](capi-hitrace-hitraceid.md)* id | 需要转换的[HiTraceId](capi-hitrace-hitraceid.md)。 | 690| uint8_t* pIdArray | 字节数组。 | 691| int len | 字节数组长度。 | 692 693**返回：** 694 695| 类型 | 说明 | 696| -- | -- | 697| int | 转换后的字节数组长度。 | 698 699### OH_HiTrace_StartTrace() 700 701``` 702void OH_HiTrace_StartTrace(const char *name) 703``` 704 705**描述** 706 707标记一个同步跟踪耗时任务的开始。<br> 同步跟踪打点接口OH_HiTrace_StartTrace()和OH_HiTrace_FinishTrace()必须配对使用。<br> OH_HiTrace_StartTrace()和OH_HiTrace_FinishTrace()函数对可以嵌套使用，跟踪解析时使用栈式数据结构进行匹配。<br> 从API version 19开始，建议使用OH_HiTrace_StartTraceEx()接口，以便分级控制跟踪输出。<br> 708 709**系统能力：** SystemCapability.HiviewDFX.HiTrace 710 711**起始版本：** 10 712 713 714**参数：** 715 716| 参数项 | 描述 | 717| -- | -- | 718| const char *name | 跟踪的名字。 | 719 720### OH_HiTrace_FinishTrace() 721 722``` 723void OH_HiTrace_FinishTrace(void) 724``` 725 726**描述** 727 728标记一个同步跟踪耗时任务的结束。<br> 必须和OH_HiTrace_StartTrace()配对使用。跟踪解析时，和其前执行流程中最近的OH_HiTrace_StartTrace()进行匹配。<br> 从API version 19开始，建议使用OH_HiTrace_FinishTraceEx()接口，以便分级控制跟踪输出。<br> 729 730**系统能力：** SystemCapability.HiviewDFX.HiTrace 731 732**起始版本：** 10 733 734### OH_HiTrace_StartAsyncTrace() 735 736``` 737void OH_HiTrace_StartAsyncTrace(const char *name, int32_t taskId) 738``` 739 740**描述** 741 742标记一个异步跟踪耗时任务的开始。<br> 用于在异步操作前调用进行开始打点，异步跟踪开始和结束数据由于不是顺序发生的，所以解析时需要通过一个唯一的taskId进行识别。<br> 必须和OH_HiTrace_FinishAsyncTrace()配对使用，参数name和taskId相同的开始与结束打点相匹配，构成一个异步跟踪耗时任务。<br> 如果有多个相同name的任务需要跟踪或者对同一个任务跟踪多次，并且任务同时被执行，则每次调用的taskId需不相同。<br> 如果具有相同name的任务是串行执行的，则taskId可以相同。<br> 从API version 19开始，建议使用OH_HiTrace_StartAsyncTraceEx()接口，以便分级控制跟踪输出与跟踪聚类。<br> 743 744**系统能力：** SystemCapability.HiviewDFX.HiTrace 745 746**起始版本：** 10 747 748 749**参数：** 750 751| 参数项 | 描述 | 752| -- | -- | 753| const char *name | 异步跟踪的名字。 | 754| int32_t taskId | 异步跟踪的ID。 异步跟踪开始和结束由于不是顺序发生的，所以需要通过name和每次执行唯一的taskId进行开始和结束的匹配。 | 755 756### OH_HiTrace_FinishAsyncTrace() 757 758``` 759void OH_HiTrace_FinishAsyncTrace(const char *name, int32_t taskId) 760``` 761 762**描述** 763 764标记一个异步跟踪耗时任务的结束。<br> 在异步操作完成后如回调函数中调用，进行结束打点。<br> 和OH_HiTrace_StartAsyncTrace()配对使用，参数name和taskId必须与异步跟踪的开始打点接口的对应参数值保持一致。<br> 从API version 19开始，建议使用OH_HiTrace_FinishAsyncTraceEx()接口，以便分级控制跟踪输出。<br> 765 766**系统能力：** SystemCapability.HiviewDFX.HiTrace 767 768**起始版本：** 10 769 770 771**参数：** 772 773| 参数项 | 描述 | 774| -- | -- | 775| const char *name | 异步跟踪的名字。 | 776| int32_t taskId | 异步跟踪的ID。异步跟踪开始和结束由于不是顺序发生的，所以需要通过name和每次执行唯一的taskId进行开始和结束的匹配。 | 777 778### OH_HiTrace_CountTrace() 779 780``` 781void OH_HiTrace_CountTrace(const char *name, int64_t count) 782``` 783 784**描述** 785 786用于跟踪给定整数变量名和整数值。<br> 多次执行该接口可以跟踪给定整数变量在不同时刻的数值变化。<br> 从API version 19开始，建议使用OH_HiTrace_CountTraceEx()接口，以便分级控制跟踪输出。<br> 787 788**系统能力：** SystemCapability.HiviewDFX.HiTrace 789 790**起始版本：** 10 791 792 793**参数：** 794 795| 参数项 | 描述 | 796| -- | -- | 797| const char *name | 整数变量跟踪的名字，不必与真实变量名相同。 | 798| int64_t count | 整数值。 | 799 800### OH_HiTrace_StartTraceEx() 801 802``` 803void OH_HiTrace_StartTraceEx(HiTrace_Output_Level level, const char *name, const char *customArgs) 804``` 805 806**描述** 807 808标记一个同步跟踪耗时任务的开始，分级控制跟踪输出。<br> 同步跟踪打点接口OH_HiTrace_StartTraceEx()和OH_HiTrace_FinishTraceEx()必须配对使用。<br> OH_HiTrace_StartTraceEx()和OH_HiTrace_FinishTraceEx()函数对可以嵌套使用，跟踪解析时使用栈式数据结构进行匹配。<br> 809 810**起始版本：** 19 811 812 813**参数：** 814 815| 参数项 | 描述 | 816| -- | -- | 817| [HiTrace_Output_Level](capi-trace-h.md#hitrace_output_level) level | 跟踪输出优先级。 | 818| const char *name | 同步跟踪的名字。 | 819| const char *customArgs | 键值对，多个键值对使用逗号分隔，例"key1=value1,key2=value2"。 | 820 821### OH_HiTrace_FinishTraceEx() 822 823``` 824void OH_HiTrace_FinishTraceEx(HiTrace_Output_Level level) 825``` 826 827**描述** 828 829标记一个同步跟踪耗时任务的结束，分级控制跟踪输出。<br> 必须和OH_HiTrace_StartTraceEx()配对使用，参数level必须与同步跟踪的开始打点接口OH_HiTrace_StartTraceEx()的对应参数值一致。<br> 跟踪数据解析时，和其前执行流程中最近的OH_HiTrace_StartTraceEx()进行匹配。<br> 830 831**起始版本：** 19 832 833 834**参数：** 835 836| 参数项 | 描述 | 837| -- | -- | 838| [HiTrace_Output_Level](capi-trace-h.md#hitrace_output_level) level | 跟踪输出优先级。 | 839 840### OH_HiTrace_StartAsyncTraceEx() 841 842``` 843void OH_HiTrace_StartAsyncTraceEx(HiTrace_Output_Level level, const char *name, int32_t taskId, const char *customCategory, const char *customArgs) 844``` 845 846**描述** 847 848标记一个异步跟踪耗时任务的开始，分级控制跟踪输出。<br> 用于在异步操作执行前进行开始打点，异步跟踪开始和结束数据由于不是顺序发生的，所以解析时需要通过一个唯一的taskId进行识别。<br> 和OH_HiTrace_FinishAsyncTraceEx()配对使用，参数name和taskId相同的开始与结束打点相匹配，构成一个异步跟踪耗时任务。<br> 如果有多个相同name的任务需要跟踪或者对同一个任务跟踪多次，并且任务同时被执行，则每次调用的taskId需不相同。<br> 如果具有相同name的任务是串行执行的，则taskId可以相同。<br> 不同进程的taskId不会相互干扰。<br> 849 850**起始版本：** 19 851 852 853**参数：** 854 855| 参数项 | 描述 | 856| -- | -- | 857| [HiTrace_Output_Level](capi-trace-h.md#hitrace_output_level) level | 跟踪输出优先级。 | 858| const char *name | 异步跟踪的名字。 | 859| int32_t taskId | 异步跟踪的ID。 | 860| const char *customCategory | 自定义聚类名称，用于聚合同一类异步跟踪打点。 | 861| const char *customArgs | 键值对，多个键值对使用逗号分隔，例"key1=value1,key2=value2"。 | 862 863### OH_HiTrace_FinishAsyncTraceEx() 864 865``` 866void OH_HiTrace_FinishAsyncTraceEx(HiTrace_Output_Level level, const char *name, int32_t taskId) 867``` 868 869**描述** 870 871标记一个异步跟踪耗时任务的结束，分级控制跟踪输出。<br> 用于在异步操作完成后进行结束打点，例如在回调函数中调用。<br> 和OH_HiTrace_StartAsyncTraceEx()配对使用，参数level、name和taskId必须与异步跟踪开始打点接口的对应参数值保持一致。<br> 872 873**起始版本：** 19 874 875 876**参数：** 877 878| 参数项 | 描述 | 879| -- | -- | 880| [HiTrace_Output_Level](capi-trace-h.md#hitrace_output_level) level | 跟踪输出优先级。 | 881| const char *name | 异步跟踪的名字。 | 882| int32_t taskId | 异步跟踪的ID。 | 883 884### OH_HiTrace_CountTraceEx() 885 886``` 887void OH_HiTrace_CountTraceEx(HiTrace_Output_Level level, const char *name, int64_t count) 888``` 889 890**描述** 891 892标记一个跟踪的整数变量，分级控制跟踪输出。 893 894**起始版本：** 19 895 896 897**参数：** 898 899| 参数项 | 描述 | 900| -- | -- | 901| [HiTrace_Output_Level](capi-trace-h.md#hitrace_output_level) level | 跟踪输出优先级。 | 902| const char *name | 整数变量的名称，不必与实际变量名相同。 | 903| int64_t count | 整数值。 | 904 905### OH_HiTrace_IsTraceEnabled() 906 907``` 908bool OH_HiTrace_IsTraceEnabled(void) 909``` 910 911**描述** 912 913判断当前是否开启应用trace捕获。 914 915**起始版本：** 19 916 917**返回：** 918 919| 类型 | 说明 | 920| -- | -- | 921| bool | 使用hitrace命令行工具等方式开启采集时返回true。<br> 未开启采集或停止采集后返回false，此时调用HiTraceMeter性能跟踪打点接口无效。 | 922 923 924