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 tracing.| 25 26 27### Structs 28 29| Name| Description| 30| -------- | -------- | 31| struct [HiTraceId](_hi_trace_id.md) | Defines the **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 version number of **HiTrace**.| 40| typedef enum [HiTrace_Flag](#hitrace_flag) [HiTrace_Flag](#hitrace_flag) | Defines an enum for the flag of **HiTrace**.| 41| typedef enum [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type) [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type) | Defines an enum for the tracepoint type of **HiTrace**.| 42| typedef enum [HiTrace_Communication_Mode](#hitrace_communication_mode) [HiTrace_Communication_Mode](#hitrace_communication_mode) | Defines an enum for the communication mode of **HiTrace**.| 43| typedef struct [HiTraceId](_hi_trace_id.md) HiTraceId | Defines a struct for **HiTraceId**.| 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 version numbers of **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>} | Enumerates the flags of **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>} | Enumerates the tracepoint types of **HiTrace**.| 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 communication modes of **HiTrace**.| 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 110**Description** 111 112Defines an enum for the communication mode of **HiTrace**. 113 114**System capability**: SystemCapability.HiviewDFX.HiTrace 115 116**Since**: 12 117 118 119### HiTrace_Flag 120 121``` 122typedef enum HiTrace_Flag HiTrace_Flag 123``` 124 125**Description** 126 127Defines an enum for the flag of **HiTrace**. 128 129**System capability**: SystemCapability.HiviewDFX.HiTrace 130 131**Since**: 12 132 133 134### HiTrace_Tracepoint_Type 135 136``` 137typedef enum HiTrace_Tracepoint_Type HiTrace_Tracepoint_Type 138``` 139 140**Description** 141 142Defines an enum for the tracepoint type of **HiTrace**. 143 144**System capability**: SystemCapability.HiviewDFX.HiTrace 145 146**Since**: 12 147 148 149### HiTrace_Version 150 151``` 152typedef enum HiTrace_Version HiTrace_Version 153``` 154 155**Description** 156 157Defines an enum for the version number of **HiTrace**. 158 159**System capability**: SystemCapability.HiviewDFX.HiTrace 160 161**Since**: 12 162 163 164### HiTraceId_Valid 165 166``` 167typedef enum HiTraceId_Valid HiTraceId_Valid 168``` 169 170**Description** 171 172Defines an enum for whether a **HiTraceId** instance is valid. 173 174**System capability**: SystemCapability.HiviewDFX.HiTrace 175 176**Since**: 12 177 178 179## Enum Description 180 181 182### HiTrace_Communication_Mode 183 184``` 185enum HiTrace_Communication_Mode 186``` 187 188**Description** 189 190Enumerates the communication modes of **HiTrace**. 191 192**System capability**: SystemCapability.HiviewDFX.HiTrace 193 194**Since**: 12 195 196| Value| Description| 197| -------- | -------- | 198| HITRACE_CM_DEFAULT | Unspecified<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 199| HITRACE_CM_THREAD | Inter-Thread Communication<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 200| HITRACE_CM_PROCESS | Inter-process communication (IPC)<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 201| HITRACE_CM_DEVICE | Inter-device communication<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 202 203 204### HiTrace_Flag 205 206``` 207enum HiTrace_Flag 208``` 209 210**Description** 211 212Enumerates the flags of **HiTrace**. 213 214**System capability**: SystemCapability.HiviewDFX.HiTrace 215 216**Since**: 12 217 218| Value| Description| 219| -------- | -------- | 220| HITRACE_FLAG_DEFAULT | Default value<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 221| HITRACE_FLAG_INCLUDE_ASYNC | Both synchronous and asynchronous calls are traced. By default, only synchronous calls are traced.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 222| HITRACE_FLAG_DONOT_CREATE_SPAN | Do not create a child span. By default, a child span is created.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 223| HITRACE_FLAG_TP_INFO | Trace points are automatically added to spans. By default, no trace point is added.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 224| 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 | 225| 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 | 226| HITRACE_FLAG_FAULT_TRIGGER | Tracing is triggered by faults.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 227| 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 | 228 229 230### HiTrace_Tracepoint_Type 231 232``` 233enum HiTrace_Tracepoint_Type 234``` 235 236**Description** 237 238Enumerates the tracepoint types of **HiTrace**. 239 240**System capability**: SystemCapability.HiviewDFX.HiTrace 241 242**Since**: 12 243 244| Value| Description| 245| -------- | -------- | 246| HITRACE_TP_CS | CS trace point<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 247| HITRACE_TP_CR | CR trace point<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 248| HITRACE_TP_SS | SS trace point<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 249| HITRACE_TP_SR | SR trace point<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 250| HITRACE_TP_GENERAL | General trace point<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 251 252 253### HiTrace_Version 254 255``` 256enum HiTrace_Version 257``` 258 259**Description** 260 261Enumerates the version numbers of **HiTrace**. 262 263**System capability**: SystemCapability.HiviewDFX.HiTrace 264 265**Since**: 12 266 267| Value| Description| 268| -------- | -------- | 269| HITRACE_VER_1 | Version 1<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 270 271 272### HiTraceId_Valid 273 274``` 275enum HiTraceId_Valid 276``` 277 278**Description** 279 280Enumerates whether a **HiTraceId** instance is valid. 281 282**System capability**: SystemCapability.HiviewDFX.HiTrace 283 284**Since**: 12 285 286| Value| Description| 287| -------- | -------- | 288| HITRACE_ID_INVALID | Invalid **HiTraceId**.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 289| HITRACE_ID_VALID | Valid **HiTraceId**.<br>SysCap:<br>SystemCapability.HiviewDFX.HiTrace | 290 291 292## Function Description 293 294 295### OH_HiTrace_BeginChain() 296 297``` 298HiTraceId OH_HiTrace_BeginChain (const char * name, int flags ) 299``` 300 301**Description** 302 303Starts tracing a process. 304 305This 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. 306 307**System capability**: SystemCapability.HiviewDFX.HiTrace 308 309**Since**: 12 310 311**Parameters** 312 313| Name| Description| 314| -------- | -------- | 315| name | Name of the traced service.| 316| flags | Flags of the tracing. For details, see [HiTrace_Flag](#hitrace_flag). | 317 318**Returns** 319 320Generated **HitraceId**. For details, see [HiTraceId](_hi_trace_id.md). 321 322 323### OH_HiTrace_ClearId() 324 325``` 326void OH_HiTrace_ClearId (void ) 327``` 328 329**Description** 330 331Clears the trace ID of the calling thread and invalidates it. 332 333This API clears the **HiTraceId** instance in the TLS of the calling thread. 334 335**System capability**: SystemCapability.HiviewDFX.HiTrace 336 337**Since**: 12 338 339 340### OH_HiTrace_CountTrace() 341 342``` 343void OH_HiTrace_CountTrace (const char * name, int64_t count ) 344``` 345 346**Description** 347 348Traces the value change of an integer variable based on its name. 349 350This API can be executed for multiple times to trace the value change of a given integer variable at different time points. 351 352**Since**: 10 353 354**Parameters** 355 356| Name| Description| 357| -------- | -------- | 358| name | Name of the integer variable. It does not need to be the same as the real variable name.| 359| count | Integer value. Generally, an integer variable can be specified.| 360 361 362### OH_HiTrace_CreateSpan() 363 364``` 365HiTraceId OH_HiTrace_CreateSpan (void ) 366``` 367 368**Description** 369 370Creates a span ID based on the trace ID of the calling thread. 371 372This API generates a new span and corresponding **HiTraceId** instance based on the **HiTraceId** instance in the TLS of the calling thread. 373 374**System capability**: SystemCapability.HiviewDFX.HiTrace 375 376**Since**: 12 377 378**Returns** 379 380Valid span trace ID. For details, see [HiTraceId](_hi_trace_id.md). If span ID cannot be created, the ID of the calling thread is traced. 381 382 383### OH_HiTrace_EnableFlag() 384 385``` 386void OH_HiTrace_EnableFlag (const HiTraceId * id, HiTrace_Flag flag ) 387``` 388 389**Description** 390 391Enables the specified trace flag in a **HiTraceId** instance. 392 393Sets trace flags in a **HiTraceId** instance. 394 395**System capability**: SystemCapability.HiviewDFX.HiTrace 396 397**Since**: 12 398 399**Parameters** 400 401| Name| Description| 402| -------- | -------- | 403| id | The trace ID for which the flag needs to be enabled. For details, see [HiTraceId](_hi_trace_id.md). | 404| flag | The specified trace flag needs to be enabled in the trace ID. For details, see [HiTrace_Flag](#hitrace_flag).| 405 406 407### OH_HiTrace_EndChain() 408 409``` 410void OH_HiTrace_EndChain () 411``` 412 413**Description** 414 415Stops tracing the process and clears the trace ID of the calling thread if the given trace ID is valid. Otherwise, no operation is performed. 416 417 418 419**System capability**: SystemCapability.HiviewDFX.HiTrace 420 421**Since**: 12 422 423 424### OH_HiTrace_FinishAsyncTrace() 425 426``` 427void OH_HiTrace_FinishAsyncTrace (const char * name, int32_t taskId ) 428``` 429 430**Description** 431 432Marks the end of an asynchronous trace. 433 434This API is called in the callback function after an asynchronous trace is complete. It is used with **OH_HiTrace_StartAsyncTrace** in pairs. Its name and task ID must be the same as those of **OH_HiTrace_StartAsyncTrace**. 435 436**Since**: 10 437 438**Parameters** 439 440| Name| Description| 441| -------- | -------- | 442| name | Name of the asynchronous trace.| 443| 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.| 444 445 446### OH_HiTrace_FinishTrace() 447 448``` 449void OH_HiTrace_FinishTrace (void ) 450``` 451 452**Description** 453 454Marks the end of a synchronous trace. 455 456This 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. 457 458**Since**: 10 459 460 461### OH_HiTrace_GetChainId() 462 463``` 464uint64_t OH_HiTrace_GetChainId (const HiTraceId * id) 465``` 466 467**Description** 468 469Obtains a trace chain ID. 470 471**System capability**: SystemCapability.HiviewDFX.HiTrace 472 473**Since**: 12 474 475**Parameters** 476 477| Name| Description| 478| -------- | -------- | 479| id | **HiTraceId** instance for which you want to obtain the trace chain ID. For details, see [HiTraceId](_hi_trace_id.md).| 480 481**Returns** 482 483The trace chain ID of the specified **HiTraceId** instance. 484 485### OH_HiTrace_GetFlags() 486 487``` 488int OH_HiTrace_GetFlags (const HiTraceId * id) 489``` 490 491**Description** 492 493Obtains the trace flags in a **HiTraceId** instance. 494 495**System capability**: SystemCapability.HiviewDFX.HiTrace 496 497**Since**: 12 498 499**Parameters** 500 501| Name| Description| 502| -------- | -------- | 503| id | **HiTraceId** instance for which you want to obtain the flag. For details, see [HiTraceId](_hi_trace_id.md).| 504 505**Returns** 506 507The trace flag set in the specified **HiTraceId** instance. 508 509 510### OH_HiTrace_GetId() 511 512``` 513HiTraceId OH_HiTrace_GetId () 514``` 515**Description** 516Obtains the trace ID of the calling thread. If the calling thread does not have a trace ID, an invalid trace ID is returned. 517 518Obtains the trace ID in TLS of the calling thread. 519 520**System capability**: SystemCapability.HiviewDFX.HiTrace 521 522**Since**: 12 523 524**Returns** 525 526[HiTraceId](_hi_trace_id.md) of the calling thread. If the calling thread does not have a trace ID, an invalid trace ID is returned. 527 528 529### OH_HiTrace_GetParentSpanId() 530 531``` 532uint64_t OH_HiTrace_GetParentSpanId (const HiTraceId * id) 533``` 534 535**Description** 536 537Obtains the parent span ID in a **HiTraceId** instance. 538 539**System capability**: SystemCapability.HiviewDFX.HiTrace 540 541**Since**: 12 542 543**Parameters** 544 545| Name| Description| 546| -------- | -------- | 547| id | **HiTraceId** instance for which you want to obtain the parent span ID. For details, see [HiTraceId](_hi_trace_id.md).| 548 549**Returns** 550 551The parent span ID in the specified **HiTraceId** instance. 552 553 554### OH_HiTrace_GetSpanId() 555 556``` 557uint64_t OH_HiTrace_GetSpanId (const HiTraceId * id) 558``` 559 560**Description** 561 562Obtains the span ID in a **HiTraceId** instance. 563 564**System capability**: SystemCapability.HiviewDFX.HiTrace 565 566**Since**: 12 567 568**Parameters** 569 570| Name| Description| 571| -------- | -------- | 572| id | **HiTraceId** instance for which you want to obtain the span ID. For details, see [HiTraceId](_hi_trace_id.md).| 573 574**Returns** 575 576The span ID in the specified **HiTraceId** instance. 577 578### OH_HiTrace_IdFromBytes() 579 580``` 581void OH_HiTrace_IdFromBytes (HiTraceId * id, const uint8_t * pIdArray, int len ) 582``` 583 584**Description** 585 586Creates a **HiTraceId** instance based on a byte array. 587 588**System capability**: SystemCapability.HiviewDFX.HiTrace 589 590**Since**: 12 591 592**Parameters** 593 594| Name| Description| 595| -------- | -------- | 596| id | **[HiTraceId](_hi_trace_id.md)** instance to create. | 597| pIdArray | Byte array. | 598| len | Length of the byte array.| 599 600 601### OH_HiTrace_IdToBytes() 602 603``` 604int OH_HiTrace_IdToBytes (const HiTraceId * id, uint8_t * pIdArray, int len ) 605``` 606 607**Description** 608 609Converts a **HiTraceId** instance into a byte array for caching or transfer. 610 611**System capability**: SystemCapability.HiviewDFX.HiTrace 612 613**Since**: 12 614 615**Parameters** 616 617| Name| Description| 618| -------- | -------- | 619| id | **HiTraceId** instance to convert. For details, see [HiTraceId](_hi_trace_id.md). | 620| pIdArray | Byte array. | 621| len | Length of the byte array.| 622 623**Returns** 624 625The length of the byte array after conversion. 626 627### OH_HiTrace_InitId() 628 629``` 630void OH_HiTrace_InitId (HiTraceId * id) 631``` 632 633**Description** 634 635Initializes a **HiTraceId** instance. 636 637**System capability**: SystemCapability.HiviewDFX.HiTrace 638 639**Since**: 12 640 641**Parameters** 642 643| Name| Description| 644| -------- | -------- | 645| id | **[HiTraceId](_hi_trace_id.md)** instance to initialize.| 646 647 648### OH_HiTrace_IsFlagEnabled() 649 650``` 651bool OH_HiTrace_IsFlagEnabled (const HiTraceId * id, HiTrace_Flag flag ) 652``` 653 654**Description** 655 656Checks whether the specified trace flag is enabled in a **HiTraceId** instance. 657 658 659 660**System capability**: SystemCapability.HiviewDFX.HiTrace 661 662**Since**: 12 663 664**Parameters** 665 666| Name| Description| 667| -------- | -------- | 668| id | **HiTraceId** instance to check. For details, see [HiTraceId](_hi_trace_id.md). | 669| flag | Specified trace flag. For details, see [HiTrace_Flag](#hitrace_flag). | 670 671**Returns** 672 673Returns **true** if the specified trace flag is enabled; returns **false** otherwise. 674 675 676### OH_HiTrace_IsIdValid() 677 678``` 679bool OH_HiTrace_IsIdValid (const HiTraceId * id) 680``` 681 682**Description** 683 684Checks whether a **HiTraceId** instance is valid. 685 686 687 688**System capability**: SystemCapability.HiviewDFX.HiTrace 689 690**Since**: 12 691 692**Parameters** 693 694| Name| Description| 695| -------- | -------- | 696| id | **HiTraceId** instance to check. For details, see [HiTraceId](_hi_trace_id.md). | 697 698**Returns** 699 700Returns **true** if the **HiTraceId** instance is valid; returns **false** otherwise. 701 702 703### OH_HiTrace_SetChainId() 704 705``` 706void OH_HiTrace_SetChainId (HiTraceId * id, uint64_t chainId ) 707``` 708 709**Description** 710 711Sets the trace chain ID in a **HiTraceId** instance. 712 713**System capability**: SystemCapability.HiviewDFX.HiTrace 714 715**Since**: 12 716 717**Parameters** 718 719| Name| Description| 720| -------- | -------- | 721| id | **HiTraceId** instance. For details, see [HiTraceId](_hi_trace_id.md). | 722| chainId | Trace chain ID to set.| 723 724 725### OH_HiTrace_SetFlags() 726 727``` 728void OH_HiTrace_SetFlags (HiTraceId * id, int flags ) 729``` 730 731**Description** 732 733Sets trace flags in a **HiTraceId** instance. 734 735**System capability**: SystemCapability.HiviewDFX.HiTrace 736 737**Since**: 12 738 739**Parameters** 740 741| Name| Description| 742| -------- | -------- | 743| id | **HiTraceId** instance. For details, see [HiTraceId](_hi_trace_id.md). | 744| flags | Trace flag to set. For details, see [HiTrace_Flag](#hitrace_flag).| 745 746 747### OH_HiTrace_SetId() 748 749``` 750void OH_HiTrace_SetId (const HiTraceId * id) 751``` 752 753**Description** 754 755Sets the trace ID of the calling thread. If the ID is invalid, no operation is performed. 756 757This API sets a **HiTraceId** instance to the TLS of the calling thread. 758 759**System capability**: SystemCapability.HiviewDFX.HiTrace 760 761**Since**: 12 762 763**Parameters** 764 765| Name| Description| 766| -------- | -------- | 767| id | Sets the trace ID of the calling thread. For details, see [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**Description** 777 778Sets the **ParentSpanId** in a **HiTraceId** instance. 779 780**System capability**: SystemCapability.HiviewDFX.HiTrace 781 782**Since**: 12 783 784**Parameters** 785 786| Name| Description| 787| -------- | -------- | 788| id | **HiTraceId** instance. For details, see [HiTraceId](_hi_trace_id.md). | 789| parentSpanId | Parent span ID to set.| 790 791 792### OH_HiTrace_SetSpanId() 793 794``` 795void OH_HiTrace_SetSpanId (HiTraceId * id, uint64_t spanId ) 796``` 797 798**Description** 799 800Sets the span ID in a **HiTraceId** instance. 801 802**System capability**: SystemCapability.HiviewDFX.HiTrace 803 804**Since**: 12 805 806**Parameters** 807 808| Name| Description| 809| -------- | -------- | 810| id | **HiTraceId** instance for which you want to set the span ID. | 811| spanId | Span ID to set.| 812 813 814### OH_HiTrace_StartAsyncTrace() 815 816``` 817void OH_HiTrace_StartAsyncTrace (const char * name, int32_t taskId ) 818``` 819 820**Description** 821 822Marks the start of an asynchronous trace. 823 824This 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. This 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. If 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**. If the trace tasks with the same name are not performed at the same time, the same taskId can be used. 825 826**Since**: 10 827 828**Parameters** 829 830| Name| Description| 831| -------- | -------- | 832| name | Name of the asynchronous trace.| 833| 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.| 834 835 836### OH_HiTrace_StartTrace() 837 838``` 839void OH_HiTrace_StartTrace (const char * name) 840``` 841 842**Description** 843 844Marks the start of a synchronous trace. 845 846This 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. 847 848**Since**: 10 849 850**Parameters** 851 852| Name| Description| 853| -------- | -------- | 854| name | Name of the synchronous trace.| 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**Description** 864 865Prints HiTrace information, including the trace ID. 866 867This API prints trace point information, including the communication mode, trace point type, timestamp, and span. 868 869**System capability**: SystemCapability.HiviewDFX.HiTrace 870 871**Since**: 12 872 873**Parameters** 874 875| Name| Description| 876| -------- | -------- | 877| mode | Communication mode for the trace point. For details, see [HiTrace_Communication_Mode](#hitrace_communication_mode). | 878| type | Trace point type. For details, see [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type). | 879| id | Trace ID. For details, see [HiTraceId](_hi_trace_id.md). | 880| fmt | Custom information to print.| 881 882 883## Variable Description 884 885 886### chainId 887 888``` 889uint64_t HiTraceId::chainId 890``` 891 892**Description** 893 894Chain ID of **HiTraceId**. 895 896 897### flags 898 899``` 900uint64_t HiTraceId::flags 901``` 902 903**Description** 904 905Flag of **HiTraceId**. 906 907 908### parentSpanId 909 910``` 911uint64_t HiTraceId::parentSpanId 912``` 913 914**Description** 915 916Parent span ID of **HiTraceId**. 917 918 919### spanId 920 921``` 922uint64_t HiTraceId::spanId 923``` 924 925**Description** 926 927Span ID of **HiTraceId**. 928 929 930### valid 931 932``` 933uint64_t HiTraceId::valid 934``` 935 936**Description** 937 938Whether a **HiTraceId** instance is valid. 939 940 941### ver 942 943``` 944uint64_t HiTraceId::ver 945``` 946 947**Description** 948 949Version number of **HiTraceId**. 950