1# HiTrace 2 3 4## Overview 5 6HiTraceMeter provides APIs for system performance tracing. 7 8You can call the APIs provided by HiTraceMeter in your own service logic to effectively track service processes and check the system performance. 9 10HiTraceChain provides APIs for cross-thread and cross-process distributed tracing. HiTraceChain generates a unique chain ID for a service process and passes it to various information (including application events, system events, and logs) specific to the service process. During debugging and fault locating, you can use the unique chain ID to quickly correlate various information related to the service process. 11 12**System capability**: SystemCapability.HiviewDFX.HiTrace 13 14**Since**: 10 15 16 17## Summary 18 19 20### Files 21 22| Name| Description| 23| -------- | -------- | 24| [trace.h](trace_8h.md) | Defines APIs of the HiTraceMeter module for performance trace. | 25 26 27### Structs 28 29| Name| Description| 30| -------- | -------- | 31| struct [HiTraceId](_hi_trace_id.md) | Defines a **HiTraceId** instance. | 32 33 34### Types 35 36| Name| Description| 37| -------- | -------- | 38| typedef enum [HiTraceId_Valid](#hitraceid_valid) [HiTraceId_Valid](#hitraceid_valid) | Defines an enum for whether a **HiTraceId** instance is valid. | 39| typedef enum [HiTrace_Version](#hitrace_version) [HiTrace_Version](#hitrace_version) | Defines an enum for the HiTrace versions. | 40| typedef enum [HiTrace_Flag](#hitrace_flag) [HiTrace_Flag](#hitrace_flag) | Defines an enum for the HiTrace flags. | 41| typedef enum [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type) [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type) | Defines an enum for the HiTrace tracepoint types. | 42| typedef enum [HiTrace_Communication_Mode](#hitrace_communication_mode) [HiTrace_Communication_Mode](#hitrace_communication_mode) | Defines an enum for the HiTrace communication modes. | 43| typedef struct [HiTraceId](_hi_trace_id.md) [HiTraceId](_hi_trace_id.md) | Defines a struct for the HiTrace ID.| 44 45 46### Enums 47 48| Name| Description| 49| -------- | -------- | 50| [HiTraceId_Valid](#hitraceid_valid) { HITRACE_ID_INVALID = 0, HITRACE_ID_VALID = 1 } | Enumerates whether a **HiTraceId** instance is valid. | 51| [HiTrace_Version](#hitrace_version) { HITRACE_VER_1 = 0 } | Enumerates the HiTrace versions. | 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>} | Enumerates the HiTrace flags. | 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>} | Enumerates the HiTrace tracepoint types. | 54| [HiTrace_Communication_Mode](#hitrace_communication_mode) { HITRACE_CM_DEFAULT = 0, HITRACE_CM_THREAD = 1, HITRACE_CM_PROCESS = 2, HITRACE_CM_DEVICE = 3 } | Enumerates the HiTrace communication modes. | 55 56 57### Functions 58 59| Name| Description| 60| -------- | -------- | 61| [HiTraceId](_hi_trace_id.md) [OH_HiTrace_BeginChain](#oh_hitrace_beginchain) (const char \*name, int flags) | Starts tracing a process. | 62| void [OH_HiTrace_EndChain](#oh_hitrace_endchain) () | Stops tracing the process and clears the trace ID of the calling thread if the given trace ID is valid. Otherwise, no operation is performed. | 63| [HiTraceId](_hi_trace_id.md) [OH_HiTrace_GetId](#oh_hitrace_getid) () | Obtains the trace ID of the calling thread. If the calling thread does not have a trace ID, an invalid trace ID is returned. | 64| void [OH_HiTrace_SetId](#oh_hitrace_setid) (const [HiTraceId](_hi_trace_id.md) \*id) | Sets the trace ID of the calling thread. If the ID is invalid, no operation is performed. | 65| void [OH_HiTrace_ClearId](#oh_hitrace_clearid) (void) | Clears the trace ID of the calling thread and invalidates it. | 66| [HiTraceId](_hi_trace_id.md) [OH_HiTrace_CreateSpan](#oh_hitrace_createspan) (void) | Creates a span ID based on the trace ID of the calling thread. | 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,...) | Prints HiTrace information, including the trace ID. | 68| void [OH_HiTrace_InitId](#oh_hitrace_initid) ([HiTraceId](_hi_trace_id.md) \*id) | Initializes a **HiTraceId** instance. | 69| void [OH_HiTrace_IdFromBytes](#oh_hitrace_idfrombytes) ([HiTraceId](_hi_trace_id.md) \*id, const uint8_t \*pIdArray, int len) | Creates a **HiTraceId** instance based on a byte array. | 70| bool [OH_HiTrace_IsIdValid](#oh_hitrace_isidvalid) (const [HiTraceId](_hi_trace_id.md) \*id) | Checks whether a **HiTraceId** instance is valid. | 71| bool [OH_HiTrace_IsFlagEnabled](#oh_hitrace_isflagenabled) (const [HiTraceId](_hi_trace_id.md) \*id, [HiTrace_Flag](#hitrace_flag) flag) | Checks whether the specified trace flag is enabled in a **HiTraceId** instance . | 72| void [OH_HiTrace_EnableFlag](#oh_hitrace_enableflag) (const [HiTraceId](_hi_trace_id.md) \*id, [HiTrace_Flag](#hitrace_flag) flag) | Enables the specified trace flag in a **HiTraceId** instance. | 73| int [OH_HiTrace_GetFlags](#oh_hitrace_getflags) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains the trace flags in a **HiTraceId** instance. | 74| void [OH_HiTrace_SetFlags](#oh_hitrace_setflags) ([HiTraceId](_hi_trace_id.md) \*id, int flags) | Sets trace flags in a **HiTraceId** instance. | 75| uint64_t [OH_HiTrace_GetChainId](#oh_hitrace_getchainid) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains a trace chain ID. | 76| void [OH_HiTrace_SetChainId](#oh_hitrace_setchainid) ([HiTraceId](_hi_trace_id.md) \*id, uint64_t chainId) | Sets the trace chain ID in a **HiTraceId** instance. | 77| uint64_t [OH_HiTrace_GetSpanId](#oh_hitrace_getspanid) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains the span ID in a **HiTraceId** instance. | 78| void [OH_HiTrace_SetSpanId](#oh_hitrace_setspanid) ([HiTraceId](_hi_trace_id.md) \*id, uint64_t spanId) | Sets the span ID in a **HiTraceId** instance. | 79| uint64_t [OH_HiTrace_GetParentSpanId](#oh_hitrace_getparentspanid) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains the parent span ID in a **HiTraceId** instance. | 80| void [OH_HiTrace_SetParentSpanId](#oh_hitrace_setparentspanid) ([HiTraceId](_hi_trace_id.md) \*id, uint64_t parentSpanId) | Sets the **ParentSpanId** in a **HiTraceId** instance. | 81| int [OH_HiTrace_IdToBytes](#oh_hitrace_idtobytes) (const [HiTraceId](_hi_trace_id.md) \*id, uint8_t \*pIdArray, int len) | Converts a **HiTraceId** instance into a byte array for caching or transfer. | 82| void [OH_HiTrace_StartTrace](#oh_hitrace_starttrace) (const char \*name) | Marks the start of a synchronous trace. | 83| void [OH_HiTrace_FinishTrace](#oh_hitrace_finishtrace) (void) | Marks the end of a synchronous trace. | 84| void [OH_HiTrace_StartAsyncTrace](#oh_hitrace_startasynctrace) (const char \*name, int32_t taskId) | Marks the start of an asynchronous trace. | 85| void [OH_HiTrace_FinishAsyncTrace](#oh_hitrace_finishasynctrace) (const char \*name, int32_t taskId) | Marks the end of an asynchronous trace. | 86| void [OH_HiTrace_CountTrace](#oh_hitrace_counttrace) (const char \*name, int64_t count) | Traces the value change of an integer variable based on its name. | 87 88 89### Variables 90 91| Name| Description| 92| -------- | -------- | 93| uint64_t [HiTraceId::valid](#valid): 1 | Whether a **HiTraceId** instance is valid. | 94| uint64_t [HiTraceId::ver](#ver): 3 | Version number of **HiTraceId**. | 95| uint64_t [HiTraceId::chainId](#chainid): 60 | Chain ID of **HiTraceId**. | 96| uint64_t [HiTraceId::flags](#flags): 12 | Flag of **HiTraceId**. | 97| uint64_t [HiTraceId::spanId](#spanid): 26 | Span ID of **HiTraceId**. | 98| uint64_t [HiTraceId::parentSpanId](#parentspanid): 26 | Parent span ID of **HiTraceId**. | 99 100 101## Type Description 102 103 104### HiTrace_Communication_Mode 105 106``` 107typedef enum HiTrace_Communication_Mode HiTrace_Communication_Mode 108``` 109**Description** 110Defines an enum for the HiTrace communication modes. 111 112**System capability**: SystemCapability.HiviewDFX.HiTrace 113 114**Since**: 12 115 116 117### HiTrace_Flag 118 119``` 120typedef enum HiTrace_FlagHiTrace_Flag 121``` 122**Description** 123Defines an enum for the HiTrace flags. 124 125**System capability**: SystemCapability.HiviewDFX.HiTrace 126 127**Since**: 12 128 129 130### HiTrace_Tracepoint_Type 131 132``` 133typedef enum HiTrace_Tracepoint_Type HiTrace_Tracepoint_Type 134``` 135**Description** 136Defines an enum for the HiTrace tracepoint types. 137 138**System capability**: SystemCapability.HiviewDFX.HiTrace 139 140**Since**: 12 141 142 143### HiTrace_Version 144 145``` 146typedef enum HiTrace_Version HiTrace_Version 147``` 148**Description** 149Defines an enum for the HiTrace versions. 150 151**System capability**: SystemCapability.HiviewDFX.HiTrace 152 153**Since**: 12 154 155 156### HiTraceId_Valid 157 158``` 159typedef enum HiTraceId_Valid HiTraceId_Valid 160``` 161**Description** 162Defines an enum for whether a **HiTraceId** instance is valid. 163 164**System capability**: SystemCapability.HiviewDFX.HiTrace 165 166**Since**: 12 167 168 169## Enum Description 170 171 172### HiTrace_Communication_Mode 173 174``` 175enum HiTrace_Communication_Mode 176``` 177**Description** 178Enumerates the HiTrace communication modes. 179 180**System capability**: SystemCapability.HiviewDFX.HiTrace 181 182**Since**: 12 183 184| Value| Description| 185| -------- | -------- | 186| HITRACE_CM_DEFAULT | Unspecified.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 187| HITRACE_CM_THREAD | Inter-thread communication.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 188| HITRACE_CM_PROCESS | Inter-process communication (IPC).<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 189| HITRACE_CM_DEVICE | Inter-device communication.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 190 191 192### HiTrace_Flag 193 194``` 195enum HiTrace_Flag 196``` 197**Description** 198Enumerates the HiTrace flags. 199 200**System capability**: SystemCapability.HiviewDFX.HiTrace 201 202**Since**: 12 203 204| Value| Description| 205| -------- | -------- | 206| HITRACE_FLAG_DEFAULT | Default value.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 207| HITRACE_FLAG_INCLUDE_ASYNC | Both synchronous and asynchronous calls are traced. By default, only synchronous calls are traced.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 208| HITRACE_FLAG_DONOT_CREATE_SPAN | Do not create a child span. By default, a child span is created.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 209| HITRACE_FLAG_TP_INFO | Trace points are automatically added to spans. By default, no trace point is added.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 210| HITRACE_FLAG_NO_BE_INFO | Information about the start and end of the trace task is not printed. By default, information about the start and end of the trace task is printed.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 211| HITRACE_FLAG_DONOT_ENABLE_LOG | The ID is not added to the log. By default, the ID is added to the log.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 212| HITRACE_FLAG_FAULT_TRIGGER | Tracing is triggered by faults.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 213| HITRACE_FLAG_D2D_TP_INFO | Trace points are added only for call chain trace between devices. By default, device-to-device trace points are not added.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 214 215 216### HiTrace_Tracepoint_Type 217 218``` 219enum HiTrace_Tracepoint_Type 220``` 221**Description** 222Enumerates the HiTrace tracepoint types. 223 224**System capability**: SystemCapability.HiviewDFX.HiTrace 225 226**Since**: 12 227 228| Value| Description| 229| -------- | -------- | 230| HITRACE_TP_CS | CS trace point<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 231| HITRACE_TP_CR | CR trace point<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 232| HITRACE_TP_SS | SS trace point<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 233| HITRACE_TP_SR | SR trace point<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 234| HITRACE_TP_GENERAL | General trace point<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 235 236 237### HiTrace_Version 238 239``` 240enum HiTrace_Version 241``` 242**Description** 243Enumerates the HiTrace versions. 244 245**System capability**: SystemCapability.HiviewDFX.HiTrace 246 247**Since**: 12 248 249| Value| Description| 250| -------- | -------- | 251| HITRACE_VER_1 | Version 1<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 252 253 254### HiTraceId_Valid 255 256``` 257enum HiTraceId_Valid 258``` 259**Description** 260Enumerates whether a **HiTraceId** instance is valid. 261 262**System capability**: SystemCapability.HiviewDFX.HiTrace 263 264**Since**: 12 265 266| Value| Description| 267| -------- | -------- | 268| HITRACE_ID_INVALID | Invalid **HiTraceId**.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 269| HITRACE_ID_VALID | Valid **HiTraceId**.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 270 271 272## Function Description 273 274 275### OH_HiTrace_BeginChain() 276 277``` 278HiTraceId OH_HiTrace_BeginChain (const char * name, int flags ) 279``` 280**Description** 281Starts tracing a process. 282 283This API starts tracing, creates a **HiTraceId** instance, and sets it to the TLS of the calling thread. This API works only when it is called for the first time. 284 285**System capability**: SystemCapability.HiviewDFX.HiTrace 286 287**Since**: 12 288 289**Parameters** 290 291| Name| Description| 292| -------- | -------- | 293| name | Name of the traced service. | 294| flags | Flags of the tracing. For details, see [HiTrace_Flag](#hitrace_flag). | 295 296**Returns** 297 298Returns the generated **HitraceId**. For details, see [HiTraceId](_hi_trace_id.md). 299 300 301### OH_HiTrace_ClearId() 302 303``` 304void OH_HiTrace_ClearId (void ) 305``` 306**Description** 307Clears the trace ID of the calling thread and invalidates it. 308 309This API clears the **HiTraceId** instance in the TLS of the calling thread. 310 311**System capability**: SystemCapability.HiviewDFX.HiTrace 312 313**Since**: 12 314 315 316### OH_HiTrace_CountTrace() 317 318``` 319void OH_HiTrace_CountTrace (const char * name, int64_t count ) 320``` 321**Description** 322Traces the value change of an integer variable based on its name. 323 324This API can be executed for multiple times to trace the value change of a given integer variable at different time points. 325 326**Since**: 10 327 328**Parameters** 329 330| Name| Description| 331| -------- | -------- | 332| name | Name of the integer variable. It does not need to be the same as the real variable name. | 333| count | Integer value. Generally, an integer variable can be specified.| 334 335 336### OH_HiTrace_CreateSpan() 337 338``` 339HiTraceId OH_HiTrace_CreateSpan (void ) 340``` 341**Description** 342Creates a span ID based on the trace ID of the calling thread. 343 344This API generates a new span and corresponding **HiTraceId** instance based on the **HiTraceId** instance in the TLS of the calling thread. 345 346**System capability**: SystemCapability.HiviewDFX.HiTrace 347 348**Since**: 12 349 350**Returns** 351 352Returns a valid span trace ID. For details, see [HiTraceId](_hi_trace_id.md). If the span ID cannot be created, the ID of the calling thread is traced. 353 354 355### OH_HiTrace_EnableFlag() 356 357``` 358void OH_HiTrace_EnableFlag (const HiTraceId * id, HiTrace_Flag flag ) 359``` 360**Description** 361Enables the specified trace flag in a **HiTraceId** instance. 362 363Sets trace flags in a **HiTraceId** instance. 364 365**System capability**: SystemCapability.HiviewDFX.HiTrace 366 367**Since**: 12 368 369**Parameters** 370 371| Name| Description| 372| -------- | -------- | 373| id | The trace ID for which the flag needs to be enabled. For details, see [HiTraceId](_hi_trace_id.md). | 374| flag | The specified trace flag needs to be enabled in the trace ID. For details, see [HiTrace_Flag](#hitrace_flag).| 375 376 377### OH_HiTrace_EndChain() 378 379``` 380void OH_HiTrace_EndChain () 381``` 382**Description** 383Stops tracing the process and clears the trace ID of the calling thread if the given trace ID is valid. Otherwise, no operation is performed. 384 385 386 387**System capability**: SystemCapability.HiviewDFX.HiTrace 388 389**Since**: 12 390 391 392### OH_HiTrace_FinishAsyncTrace() 393 394``` 395void OH_HiTrace_FinishAsyncTrace (const char * name, int32_t taskId ) 396``` 397**Description** 398Marks the end of an asynchronous trace. 399 400This API is called in the callback function after an asynchronous trace is complete. 401 402It is used with **OH_HiTrace_StartAsyncTrace** in pairs. Its name and task ID must be the same as those of **OH_HiTrace_StartAsyncTrace**. 403 404**Since**: 10 405 406**Parameters** 407 408| Name| Description| 409| -------- | -------- | 410| name | Name of the asynchronous trace. | 411| taskId | ID of the asynchronous trace. The start and end of an asynchronous trace task do not occur in sequence. Therefore, the start and end of an asynchronous trace need to be matched based on the task name and the unique task ID together.| 412 413 414### OH_HiTrace_FinishTrace() 415 416``` 417void OH_HiTrace_FinishTrace (void ) 418``` 419**Description** 420Marks the end of a synchronous trace. 421 422This API must be used with **OH_HiTrace_StartTrace** in pairs. During trace data parsing, the system matches it with the **OH_HiTrace_StartTrace** API recently invoked in the service process. 423 424**Since**: 10 425 426 427### OH_HiTrace_GetChainId() 428 429``` 430uint64_t OH_HiTrace_GetChainId (const HiTraceId * id) 431``` 432**Description** 433Obtains a trace chain ID. 434 435**System capability**: SystemCapability.HiviewDFX.HiTrace 436 437**Since**: 12 438 439**Parameters** 440 441| Name| Description| 442| -------- | -------- | 443| id | **HiTraceId** instance for which you want to obtain the trace chain ID. For details, see [HiTraceId](_hi_trace_id.md).| 444 445**Returns** 446 447Returns the trace chain ID of the specified **HiTraceId** instance. 448 449 450### OH_HiTrace_GetFlags() 451 452``` 453int OH_HiTrace_GetFlags (const HiTraceId * id) 454``` 455**Description** 456Obtains the trace flags in a **HiTraceId** instance. 457 458**System capability**: SystemCapability.HiviewDFX.HiTrace 459 460**Since**: 12 461 462**Parameters** 463 464| Name| Description| 465| -------- | -------- | 466| id | **HiTraceId** instance for which you want to obtain the flag. For details, see [HiTraceId](_hi_trace_id.md).| 467 468**Returns** 469 470Returns the trace flags set in the specified **HiTraceId** instance. 471 472 473### OH_HiTrace_GetId() 474 475``` 476HiTraceId OH_HiTrace_GetId () 477``` 478**Description** 479Obtains the trace ID of the calling thread. If the calling thread does not have a trace ID, an invalid trace ID is returned. 480 481Obtains the trace ID in TLS of the calling thread. 482 483**System capability**: SystemCapability.HiviewDFX.HiTrace 484 485**Since**: 12 486 487**Returns** 488 489Returns the [HiTraceId](_hi_trace_id.md) of the calling thread. Returns an invalid **HiTraceId** if the calling thread does not have a **HiTraceId**. 490 491 492### OH_HiTrace_GetParentSpanId() 493 494``` 495uint64_t OH_HiTrace_GetParentSpanId (const HiTraceId * id) 496``` 497**Description** 498Obtains the parent span ID in a **HiTraceId** instance. 499 500**System capability**: SystemCapability.HiviewDFX.HiTrace 501 502**Since**: 12 503 504**Parameters** 505 506| Name| Description| 507| -------- | -------- | 508| id | **HiTraceId** instance for which you want to obtain the parent span ID. For details, see [HiTraceId](_hi_trace_id.md).| 509 510**Returns** 511 512Returns the parent span ID in the specified **HiTraceId** instance. 513 514 515### OH_HiTrace_GetSpanId() 516 517``` 518uint64_t OH_HiTrace_GetSpanId (const HiTraceId * id) 519``` 520**Description** 521Obtains the span ID in a **HiTraceId** instance. 522 523**System capability**: SystemCapability.HiviewDFX.HiTrace 524 525**Since**: 12 526 527**Parameters** 528 529| Name| Description| 530| -------- | -------- | 531| id | **HiTraceId** instance for which you want to obtain the span ID. For details, see [HiTraceId](_hi_trace_id.md).| 532 533**Returns** 534 535Returns the span ID in the specified **HiTraceId** instance. 536 537 538### OH_HiTrace_IdFromBytes() 539 540``` 541void OH_HiTrace_IdFromBytes (HiTraceId * id, const uint8_t * pIdArray, int len ) 542``` 543**Description** 544Creates a **HiTraceId** instance based on a byte array. 545 546**System capability**: SystemCapability.HiviewDFX.HiTrace 547 548**Since**: 12 549 550**Parameters** 551 552| Name| Description| 553| -------- | -------- | 554| id | **[HiTraceId](_hi_trace_id.md)** instance to create. | 555| pIdArray | Byte array. | 556| len | Length of the byte array.| 557 558 559### OH_HiTrace_IdToBytes() 560 561``` 562int OH_HiTrace_IdToBytes (const HiTraceId * id, uint8_t * pIdArray, int len ) 563``` 564**Description** 565Converts a **HiTraceId** instance into a byte array for caching or transfer. 566 567**System capability**: SystemCapability.HiviewDFX.HiTrace 568 569**Since**: 12 570 571**Parameters** 572 573| Name| Description| 574| -------- | -------- | 575| id | **HiTraceId** instance to convert. For details, see [HiTraceId](_hi_trace_id.md). | 576| pIdArray | Byte array. | 577| len | Length of the byte array.| 578 579**Returns** 580 581Returns the length of the byte array after conversion. 582 583 584### OH_HiTrace_InitId() 585 586``` 587void OH_HiTrace_InitId (HiTraceId * id) 588``` 589**Description** 590Initializes a **HiTraceId** instance. 591 592**System capability**: SystemCapability.HiviewDFX.HiTrace 593 594**Since**: 12 595 596**Parameters** 597 598| Name| Description| 599| -------- | -------- | 600| id | **[HiTraceId](_hi_trace_id.md)** instance to initialize.| 601 602 603### OH_HiTrace_IsFlagEnabled() 604 605``` 606bool OH_HiTrace_IsFlagEnabled (const HiTraceId * id, HiTrace_Flag flag ) 607``` 608**Description** 609Checks whether the specified trace flag is enabled in a **HiTraceId** instance. 610 611 612 613**System capability**: SystemCapability.HiviewDFX.HiTrace 614 615**Since**: 12 616 617**Parameters** 618 619| Name| Description| 620| -------- | -------- | 621| id | **HiTraceId** instance to check. For details, see [HiTraceId](_hi_trace_id.md). | 622| flag | Specified trace flag. For details, see [HiTrace_Flag](#hitrace_flag). | 623 624**Returns** 625 626Returns **true** if the specified trace flag is enabled; returns **false** otherwise. 627 628 629### OH_HiTrace_IsIdValid() 630 631``` 632bool OH_HiTrace_IsIdValid (const HiTraceId * id) 633``` 634**Description** 635Checks whether a **HiTraceId** instance is valid. 636 637 638 639**System capability**: SystemCapability.HiviewDFX.HiTrace 640 641**Since**: 12 642 643**Parameters** 644 645| Name| Description| 646| -------- | -------- | 647| id | **HiTraceId** instance to check. For details, see [HiTraceId](_hi_trace_id.md). | 648 649**Returns** 650 651Returns **true** if the **HiTraceId** instance is valid; returns **false** otherwise. 652 653 654### OH_HiTrace_SetChainId() 655 656``` 657void OH_HiTrace_SetChainId (HiTraceId * id, uint64_t chainId ) 658``` 659**Description** 660Sets the trace chain ID in a **HiTraceId** instance. 661 662**System capability**: SystemCapability.HiviewDFX.HiTrace 663 664**Since**: 12 665 666**Parameters** 667 668| Name| Description| 669| -------- | -------- | 670| id | **HiTraceId** instance. For details, see [HiTraceId](_hi_trace_id.md). | 671| chainId | Trace chain ID to set.| 672 673 674### OH_HiTrace_SetFlags() 675 676``` 677void OH_HiTrace_SetFlags (HiTraceId * id, int flags ) 678``` 679**Description** 680Sets trace flags in a **HiTraceId** instance. 681 682**System capability**: SystemCapability.HiviewDFX.HiTrace 683 684**Since**: 12 685 686**Parameters** 687 688| Name| Description| 689| -------- | -------- | 690| id | **HiTraceId** instance. For details, see [HiTraceId](_hi_trace_id.md). | 691| flags | Trace flag to set. For details, see [HiTrace_Flag](#hitrace_flag).| 692 693 694### OH_HiTrace_SetId() 695 696``` 697void OH_HiTrace_SetId (const HiTraceId * id) 698``` 699**Description** 700Sets the trace ID of the calling thread. If the ID is invalid, no operation is performed. 701 702This API sets a **HiTraceId** instance to the TLS of the calling thread. 703 704**System capability**: SystemCapability.HiviewDFX.HiTrace 705 706**Since**: 12 707 708**Parameters** 709 710| Name| Description| 711| -------- | -------- | 712| id | Sets the trace ID of the calling thread. For details, see [HiTraceId](_hi_trace_id.md).| 713 714 715### OH_HiTrace_SetParentSpanId() 716 717``` 718void OH_HiTrace_SetParentSpanId (HiTraceId * id, uint64_t parentSpanId ) 719``` 720**Description** 721Sets the **ParentSpanId** in a **HiTraceId** instance. 722 723**System capability**: SystemCapability.HiviewDFX.HiTrace 724 725**Since**: 12 726 727**Parameters** 728 729| Name| Description| 730| -------- | -------- | 731| id | **HiTraceId** instance. For details, see [HiTraceId](_hi_trace_id.md). | 732| parentSpanId | Parent span ID to set.| 733 734 735### OH_HiTrace_SetSpanId() 736 737``` 738void OH_HiTrace_SetSpanId (HiTraceId * id, uint64_t spanId ) 739``` 740**Description** 741Sets the span ID in a **HiTraceId** instance. 742 743**System capability**: SystemCapability.HiviewDFX.HiTrace 744 745**Since**: 12 746 747**Parameters** 748 749| Name| Description| 750| -------- | -------- | 751| id | **HiTraceId** instance for which you want to set the span ID. | 752| spanId | Span ID to set.| 753 754 755### OH_HiTrace_StartAsyncTrace() 756 757``` 758void OH_HiTrace_StartAsyncTrace (const char * name, int32_t taskId ) 759``` 760**Description** 761Marks the start of an asynchronous trace. 762 763This API is called to implement performance trace in asynchronous manner. The start and end of an asynchronous trace task do not occur in sequence. Therefore, a unique **taskId** is required to ensure proper data parsing. It is passed as an input parameter for the asynchronous API. 764 765This API is used with **OH_HiTrace_FinishAsyncTrace** in pairs. The two APIs that have the same name and task ID together form an asynchronous trace. 766 767If multiple trace tasks with the same name need to be performed at the same time or a trace task needs to be performed multiple times concurrently, different task IDs must be specified in **OH_HiTrace_StartTrace**. 768 769If the trace tasks with the same name are not performed at the same time, the same taskId can be used. 770 771**Since**: 10 772 773**Parameters** 774 775| Name| Description| 776| -------- | -------- | 777| name | Name of the asynchronous trace. | 778| taskId | ID of the asynchronous trace. The start and end of an asynchronous trace task do not occur in sequence. Therefore, the start and end of an asynchronous trace need to be matched based on the task name and the unique task ID together.| 779 780 781### OH_HiTrace_StartTrace() 782 783``` 784void OH_HiTrace_StartTrace (const char * name) 785``` 786**Description** 787Marks the start of a synchronous trace. 788 789This API is used with **OH_HiTrace_FinishTrace** in pairs. The two APIs can be used in nested mode. The stack data structure is used for matching during trace data parsing. 790 791**Since**: 10 792 793**Parameters** 794 795| Name| Description| 796| -------- | -------- | 797| name | Name of the synchronous trace.| 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**Description** 806Prints HiTrace information, including the trace ID. 807 808This API prints trace point information, including the communication mode, trace point type, timestamp, and span. 809 810**System capability**: SystemCapability.HiviewDFX.HiTrace 811 812**Since**: 12 813 814**Parameters** 815 816| Name| Description| 817| -------- | -------- | 818| mode | Communication mode for the trace point. For details, see [HiTrace_Communication_Mode](#hitrace_communication_mode). | 819| type | Trace point type. For details, see [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type). | 820| id | Trace ID. For details, see [HiTraceId](_hi_trace_id.md). | 821| fmt | Custom information to print.| 822 823 824## Variable Description 825 826 827### chainId 828 829``` 830uint64_t HiTraceId::chainId 831``` 832**Description** 833Chain ID of **HiTraceId**. 834 835 836### flags 837 838``` 839uint64_t HiTraceId::flags 840``` 841**Description** 842Flag of **HiTraceId**. 843 844 845### parentSpanId 846 847``` 848uint64_t HiTraceId::parentSpanId 849``` 850**Description** 851Parent span ID of **HiTraceId**. 852 853 854### spanId 855 856``` 857uint64_t HiTraceId::spanId 858``` 859**Description** 860Span ID of **HiTraceId**. 861 862 863### valid 864 865``` 866uint64_t HiTraceId::valid 867``` 868**Description** 869Whether a **HiTraceId** instance is valid. 870 871 872### ver 873 874``` 875uint64_t HiTraceId::ver 876``` 877**Description** 878Version number of **HiTraceId**. 879