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