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