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