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. 11 12HiTraceChain 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. 13 14**System capability**: SystemCapability.HiviewDFX.HiTrace 15 16**Since**: 10 17 18 19## Summary 20 21 22### Files 23 24| Name| Description| 25| -------- | -------- | 26| [trace.h](trace_8h.md) | Defines APIs of the HiTraceMeter module for performance trace. | 27 28 29### Structs 30 31| Name| Description| 32| -------- | -------- | 33| struct [HiTraceId](_hi_trace_id.md) | Defines a **HiTraceId** instance. | 34 35 36### Types 37 38| Name| Description| 39| -------- | -------- | 40| typedef enum [HiTraceId_Valid](#hitraceid_valid) [HiTraceId_Valid](#hitraceid_valid) | Defines an enum for whether a **HiTraceId** instance is valid. | 41| typedef enum [HiTrace_Version](#hitrace_version) [HiTrace_Version](#hitrace_version) | Defines an enum for the HiTrace versions. | 42| typedef enum [HiTrace_Flag](#hitrace_flag) [HiTrace_Flag](#hitrace_flag) | Defines an enum for the HiTrace flags. | 43| typedef enum [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type) [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type) | Defines an enum for the HiTrace tracepoint types. | 44| typedef enum [HiTrace_Communication_Mode](#hitrace_communication_mode) [HiTrace_Communication_Mode](#hitrace_communication_mode) | Defines an enum for the HiTrace communication modes. | 45| typedef enum [HiTrace_Output_Level](#hitrace_output_level) [HiTrace_Output_Level](#hitrace_output_level) | Defines an enum for the HiTrace output levels. | 46| typedef struct [HiTraceId](_hi_trace_id.md)**HiTraceId** | | 47 48 49### Enums 50 51| Name| Description| 52| -------- | -------- | 53| [HiTraceId_Valid](#hitraceid_valid) { HITRACE_ID_INVALID = 0, HITRACE_ID_VALID = 1 } | Enumerates whether a **HiTraceId** instance is valid. | 54| [HiTrace_Version](#hitrace_version) { HITRACE_VER_1 = 0 } | Enumerates the HiTrace versions. | 55| [HiTrace_Flag](#hitrace_flag) {<br>HITRACE_FLAG_DEFAULT = 0, HITRACE_FLAG_INCLUDE_ASYNC = 1 << 0, HITRACE_FLAG_DONOT_CREATE_SPAN = 1 << 1, HITRACE_FLAG_TP_INFO = 1 << 2,<br>HITRACE_FLAG_NO_BE_INFO = 1 << 3, HITRACE_FLAG_DONOT_ENABLE_LOG = 1 << 4, HITRACE_FLAG_FAULT_TRIGGER = 1 << 5, HITRACE_FLAG_D2D_TP_INFO = 1 << 6<br>} | Enumerates the HiTrace flags. | 56| [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type) {<br>HITRACE_TP_CS = 0, HITRACE_TP_CR = 1, HITRACE_TP_SS = 2, HITRACE_TP_SR = 3,<br>HITRACE_TP_GENERAL = 4<br>} | Enumerates the HiTrace tracepoint types. | 57| [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. | 58| [HiTrace_Output_Level](#hitrace_output_level) {<br>HITRACE_LEVEL_DEBUG = 0, HITRACE_LEVEL_INFO = 1, HITRACE_LEVEL_CRITICAL = 2, HITRACE_LEVEL_COMMERCIAL = 3,<br>HITRACE_LEVEL_MAX = HITRACE_LEVEL_COMMERCIAL<br>} | Enumerates the HiTrace output levels. | 59 60 61### Functions 62 63| Name| Description| 64| -------- | -------- | 65| [HiTraceId](_hi_trace_id.md) [OH_HiTrace_BeginChain](#oh_hitrace_beginchain) (const char \*name, int flags) | Starts tracing a process. | 66| 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. | 67| [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. | 68| 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. | 69| void [OH_HiTrace_ClearId](#oh_hitrace_clearid) (void) | Clears the trace ID of the calling thread and invalidates it. | 70| [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. | 71| void [OH_HiTrace_Tracepoint](#oh_hitrace_tracepoint) ([HiTrace_Communication_Mode](#hitrace_communication_mode) mode, [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type) type, const [HiTraceId](_hi_trace_id.md) \*id, const char \*fmt,...) | Prints HiTrace information, including the trace ID. | 72| void [OH_HiTrace_InitId](#oh_hitrace_initid) ([HiTraceId](_hi_trace_id.md) \*id) | Initializes a **HiTraceId** instance. | 73| 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. | 74| bool [OH_HiTrace_IsIdValid](#oh_hitrace_isidvalid) (const [HiTraceId](_hi_trace_id.md) \*id) | Checks whether a **HiTraceId** instance is valid. | 75| 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 . | 76| 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. | 77| int [OH_HiTrace_GetFlags](#oh_hitrace_getflags) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains the trace flags in a **HiTraceId** instance. | 78| void [OH_HiTrace_SetFlags](#oh_hitrace_setflags) ([HiTraceId](_hi_trace_id.md) \*id, int flags) | Sets trace flags in a **HiTraceId** instance. | 79| uint64_t [OH_HiTrace_GetChainId](#oh_hitrace_getchainid) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains a trace chain ID. | 80| 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. | 81| uint64_t [OH_HiTrace_GetSpanId](#oh_hitrace_getspanid) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains the span ID in a **HiTraceId** instance. | 82| void [OH_HiTrace_SetSpanId](#oh_hitrace_setspanid) ([HiTraceId](_hi_trace_id.md) \*id, uint64_t spanId) | Sets the span ID in a **HiTraceId** instance. | 83| uint64_t [OH_HiTrace_GetParentSpanId](#oh_hitrace_getparentspanid) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains the parent span ID in a **HiTraceId** instance. | 84| void [OH_HiTrace_SetParentSpanId](#oh_hitrace_setparentspanid) ([HiTraceId](_hi_trace_id.md) \*id, uint64_t parentSpanId) | Sets the **ParentSpanId** in a **HiTraceId** instance. | 85| 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. | 86| void [OH_HiTrace_StartTrace](#oh_hitrace_starttrace) (const char \*name) | Marks the start of a synchronous trace. | 87| void [OH_HiTrace_FinishTrace](#oh_hitrace_finishtrace) (void) | Marks the end of a synchronous trace. | 88| void [OH_HiTrace_StartAsyncTrace](#oh_hitrace_startasynctrace) (const char \*name, int32_t taskId) | Marks the start of an asynchronous trace. | 89| void [OH_HiTrace_FinishAsyncTrace](#oh_hitrace_finishasynctrace) (const char \*name, int32_t taskId) | Marks the end of an asynchronous trace. | 90| 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. | 91| void [OH_HiTrace_StartTraceEx](#oh_hitrace_starttraceex) ([HiTrace_Output_Level](#hitrace_output_level) level, const char \*name, const char \*customArgs) | Marks the start of a synchronous trace task with the trace output level specified. | 92| void [OH_HiTrace_FinishTraceEx](#oh_hitrace_finishtraceex) ([HiTrace_Output_Level](#hitrace_output_level) level) | Marks the end of a synchronous trace task with the trace output level specified. | 93| void [OH_HiTrace_StartAsyncTraceEx](#oh_hitrace_startasynctraceex) ([HiTrace_Output_Level](#hitrace_output_level) level, const char \*name, int32_t taskId, const char \*customCategory, const char \*customArgs) | Marks the start of an asynchronous trace task with the trace output level specified. | 94| void [OH_HiTrace_FinishAsyncTraceEx](#oh_hitrace_finishasynctraceex) ([HiTrace_Output_Level](#hitrace_output_level) level, const char \*name, int32_t taskId) | Marks the end of an asynchronous trace task with the trace output level specified. | 95| void [OH_HiTrace_CountTraceEx](#oh_hitrace_counttraceex) ([HiTrace_Output_Level](#hitrace_output_level) level, const char \*name, int64_t count) | Marks an integer variable trace task with the trace output level specified. | 96| bool [OH_HiTrace_IsTraceEnabled](#oh_hitrace_istraceenabled) (void) | Checks whether trace capture is enabled for an application. If not, HiTraceMeter performance tracing is invalid. | 97 98 99## Type Description 100 101 102### HiTrace_Communication_Mode 103 104``` 105typedef enum HiTrace_Communication_ModeHiTrace_Communication_Mode 106``` 107**Description** 108Defines an enum for the HiTrace communication modes. 109 110**System capability**: SystemCapability.HiviewDFX.HiTrace 111 112**Since**: 12 113 114 115### HiTrace_Flag 116 117``` 118typedef enum HiTrace_FlagHiTrace_Flag 119``` 120**Description** 121Defines an enum for the HiTrace flags. 122 123**System capability**: SystemCapability.HiviewDFX.HiTrace 124 125**Since**: 12 126 127 128### HiTrace_Output_Level 129 130``` 131typedef enum HiTrace_Output_LevelHiTrace_Output_Level 132``` 133**Description** 134Defines an enum for the HiTrace output levels. 135 136The trace output level lower than the threshold does not take effect. The log version threshold is **HITRACE_LEVEL_INFO**, and the nolog version threshold is **HITRACE_LEVEL_COMMERCIAL**. 137 138 139 140**System capability**: SystemCapability.HiviewDFX.HiTrace 141 142**Since**: 19 143 144 145### HiTrace_Tracepoint_Type 146 147``` 148typedef enum HiTrace_Tracepoint_Type HiTrace_Tracepoint_Type 149``` 150**Description** 151Defines an enum for the HiTrace tracepoint types. 152 153**System capability**: SystemCapability.HiviewDFX.HiTrace 154 155**Since**: 12 156 157 158### HiTrace_Version 159 160``` 161typedef enum HiTrace_Version HiTrace_Version 162``` 163**Description** 164Defines an enum for the HiTrace versions. 165 166**System capability**: SystemCapability.HiviewDFX.HiTrace 167 168**Since**: 12 169 170 171### HiTraceId_Valid 172 173``` 174typedef enum HiTraceId_Valid HiTraceId_Valid 175``` 176**Description** 177Defines an enum for whether a **HiTraceId** instance is valid. 178 179**System capability**: SystemCapability.HiviewDFX.HiTrace 180 181**Since**: 12 182 183 184## Enum Description 185 186 187### HiTrace_Communication_Mode 188 189``` 190enum HiTrace_Communication_Mode 191``` 192**Description** 193Enumerates the HiTrace communication modes. 194 195**System capability**: SystemCapability.HiviewDFX.HiTrace 196 197**Since**: 12 198 199| Value| Description| 200| -------- | -------- | 201| HITRACE_CM_DEFAULT | Unspecified.| 202| HITRACE_CM_THREAD | Inter-thread communication.| 203| HITRACE_CM_PROCESS | Inter-process communication (IPC).| 204| HITRACE_CM_DEVICE | Inter-device communication.| 205 206 207### HiTrace_Flag 208 209``` 210enum HiTrace_Flag 211``` 212**Description** 213Enumerates the HiTrace flags. 214 215**System capability**: SystemCapability.HiviewDFX.HiTrace 216 217**Since**: 12 218 219| Value| Description| 220| -------- | -------- | 221| HITRACE_FLAG_DEFAULT | Default value.| 222| HITRACE_FLAG_INCLUDE_ASYNC | Both synchronous and asynchronous calls are traced. By default, only synchronous calls are traced.| 223| HITRACE_FLAG_DONOT_CREATE_SPAN | No spans are created. By default, spans are created.| 224| HITRACE_FLAG_TP_INFO | Trace points are automatically added to spans. By default, no trace point is added.| 225| 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.| 226| HITRACE_FLAG_DONOT_ENABLE_LOG | The ID is not added to the log. By default, the ID is added to the log.| 227| HITRACE_FLAG_FAULT_TRIGGER | Tracing is triggered by faults.| 228| HITRACE_FLAG_D2D_TP_INFO | Only the device-to-device tracing point information in the span is output. By default, the device-to-device tracing point information is not output.| 229 230 231### HiTrace_Output_Level 232 233``` 234enum HiTrace_Output_Level 235``` 236**Description** 237Enumerates the HiTrace output levels. 238 239The trace output level lower than the threshold does not take effect. The log version threshold is **HITRACE_LEVEL_INFO**, and the nolog version threshold is **HITRACE_LEVEL_COMMERCIAL**. 240 241 242 243**System capability**: SystemCapability.HiviewDFX.HiTrace 244 245**Since**: 19 246 247| Value| Description| 248| -------- | -------- | 249| HITRACE_LEVEL_DEBUG | Level used only for debugging, which has the lowest priority.| 250| HITRACE_LEVEL_INFO | Level for the log version.| 251| HITRACE_LEVEL_CRITICAL | Level for the log version, which has a higher priority than **INFO**.| 252| HITRACE_LEVEL_COMMERCIAL | Level for the nolog version, which has the highest priority.| 253| HITRACE_LEVEL_MAX | The maximum output level.| 254 255 256### HiTrace_Tracepoint_Type 257 258``` 259enum HiTrace_Tracepoint_Type 260``` 261**Description** 262Enumerates the HiTrace tracepoint types. 263 264**System capability**: SystemCapability.HiviewDFX.HiTrace 265 266**Since**: 12 267 268| Value| Description| 269| -------- | -------- | 270| HITRACE_TP_CS | CS trace point.| 271| HITRACE_TP_CR | CR trace point.| 272| HITRACE_TP_SS | SS trace point.| 273| HITRACE_TP_SR | SR trace point.| 274| HITRACE_TP_GENERAL | General trace point.| 275 276 277### HiTrace_Version 278 279``` 280enum HiTrace_Version 281``` 282**Description** 283Enumerates the HiTrace versions. 284 285**System capability**: SystemCapability.HiviewDFX.HiTrace 286 287**Since**: 12 288 289| Value| Description| 290| -------- | -------- | 291| HITRACE_VER_1 | Version 1.| 292 293 294### HiTraceId_Valid 295 296``` 297enum HiTraceId_Valid 298``` 299**Description** 300Enumerates whether a **HiTraceId** instance is valid. 301 302**System capability**: SystemCapability.HiviewDFX.HiTrace 303 304**Since**: 12 305 306| Value| Description| 307| -------- | -------- | 308| HITRACE_ID_INVALID | Invalid **HiTraceId**.| 309| HITRACE_ID_VALID | Valid **HiTraceId**.| 310 311 312## Function Description 313 314 315### OH_HiTrace_BeginChain() 316 317``` 318HiTraceId OH_HiTrace_BeginChain (const char * name, int flags ) 319``` 320**Description** 321Starts tracing a process. 322 323This 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. 324 325**System capability**: SystemCapability.HiviewDFX.HiTrace 326 327**Since**: 12 328 329**Parameters** 330 331| Name| Description| 332| -------- | -------- | 333| name | Name of the traced service. | 334| flags | Flags of the tracing. For details, see [HiTrace_Flag](#hitrace_flag). | 335 336**Returns** 337 338Returns the generated **HitraceId**. For details, see [HiTraceId](_hi_trace_id.md). 339 340 341### OH_HiTrace_ClearId() 342 343``` 344void OH_HiTrace_ClearId (void ) 345``` 346**Description** 347Clears the trace ID of the calling thread and invalidates it. 348 349This API clears the **HiTraceId** instance in the TLS of the calling thread. 350 351**System capability**: SystemCapability.HiviewDFX.HiTrace 352 353**Since**: 12 354 355 356### OH_HiTrace_CountTrace() 357 358``` 359void OH_HiTrace_CountTrace (const char * name, int64_t count ) 360``` 361**Description** 362Traces the value change of an integer variable based on its name. 363 364This API can be executed for multiple times to trace the value change of a given integer variable at different time points. 365 366Since API version 19, you are advised to use the **OH_HiTrace_CountTraceEx** API to specify the trace output level. 367 368**System capability**: SystemCapability.HiviewDFX.HiTrace 369 370**Since**: 10 371 372**Parameters** 373 374| Name| Description| 375| -------- | -------- | 376| name | Name of the integer variable. It does not need to be the same as the real variable name. | 377| count | Integer value.| 378 379 380### OH_HiTrace_CountTraceEx() 381 382``` 383void OH_HiTrace_CountTraceEx (HiTrace_Output_Level level, const char * name, int64_t count ) 384``` 385**Description** 386Marks an integer variable trace task with the trace output level specified. 387 388**Since**: 19 389 390**Parameters** 391 392| Name| Description| 393| -------- | -------- | 394| level | Trace output level. | 395| name | Name of the integer variable. It does not need to be the same as the actual variable name. | 396| count | Integer value.| 397 398 399### OH_HiTrace_CreateSpan() 400 401``` 402HiTraceId OH_HiTrace_CreateSpan (void ) 403``` 404**Description** 405Creates a span ID based on the trace ID of the calling thread. 406 407This API generates a new span and corresponding **HiTraceId** instance based on the **HiTraceId** instance in the TLS of the calling thread. 408 409**System capability**: SystemCapability.HiviewDFX.HiTrace 410 411**Since**: 12 412 413**Returns** 414 415Returns 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. 416 417 418### OH_HiTrace_EnableFlag() 419 420``` 421void OH_HiTrace_EnableFlag (const HiTraceId * id, HiTrace_Flag flag ) 422``` 423**Description** 424Enables the specified trace flag in a **HiTraceId** instance. 425 426Sets trace flags in a **HiTraceId** instance. 427 428**System capability**: SystemCapability.HiviewDFX.HiTrace 429 430**Since**: 12 431 432**Parameters** 433 434| Name| Description| 435| -------- | -------- | 436| id | The trace ID for which the flag needs to be enabled. For details, see [HiTraceId](_hi_trace_id.md). | 437| flag | The specified trace flag needs to be enabled in the trace ID. For details, see [HiTrace_Flag](#hitrace_flag).| 438 439 440### OH_HiTrace_EndChain() 441 442``` 443void OH_HiTrace_EndChain () 444``` 445**Description** 446Stops tracing the process and clears the trace ID of the calling thread if the given trace ID is valid. Otherwise, no operation is performed. 447 448 449 450**System capability**: SystemCapability.HiviewDFX.HiTrace 451 452**Since**: 12 453 454 455### OH_HiTrace_FinishAsyncTrace() 456 457``` 458void OH_HiTrace_FinishAsyncTrace (const char * name, int32_t taskId ) 459``` 460**Description** 461Marks the end of an asynchronous trace. 462 463This API is called in the callback function after an asynchronous trace is complete. 464 465It is used with **OH_HiTrace_StartAsyncTrace** in pairs. Its name and task ID must be the same as those of **OH_HiTrace_StartAsyncTrace**. 466 467Since API version 19, you are advised to use the **OH_HiTrace_FinishAsyncTraceEx** API to specify the trace output level. 468 469**System capability**: SystemCapability.HiviewDFX.HiTrace 470 471**Since**: 10 472 473**Parameters** 474 475| Name| Description| 476| -------- | -------- | 477| name | Name of the asynchronous trace. | 478| 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.| 479 480 481### OH_HiTrace_FinishAsyncTraceEx() 482 483``` 484void OH_HiTrace_FinishAsyncTraceEx (HiTrace_Output_Level level, const char * name, int32_t taskId ) 485``` 486**Description** 487Marks the end of an asynchronous trace task with the trace output level specified. 488 489This API is used to stop tracing after an asynchronous operation is complete, for example, in a callback function. 490 491It is used with **OH_HiTrace_StartAsyncTraceEx** in pairs. Its level, name and task ID must be the same as those of **OH_HiTrace_StartAsyncTraceEx**. 492 493 494 495**Since**: 19 496 497**Parameters** 498 499| Name| Description| 500| -------- | -------- | 501| level | Trace output level. | 502| name | Name of the asynchronous trace. | 503| taskId | ID of the asynchronous trace.| 504 505 506### OH_HiTrace_FinishTrace() 507 508``` 509void OH_HiTrace_FinishTrace (void ) 510``` 511**Description** 512Marks the end of a synchronous trace. 513 514This API must be used with **OH_HiTrace_StartTrace** in pairs. During trace parsing, the system matches it with the **OH_HiTrace_StartTrace** API recently invoked in the service process. 515 516Since API version 19, you are advised to use the **OH_HiTrace_FinishTraceEx** API to specify the trace output level. 517 518**System capability**: SystemCapability.HiviewDFX.HiTrace 519 520**Since**: 10 521 522 523### OH_HiTrace_FinishTraceEx() 524 525``` 526void OH_HiTrace_FinishTraceEx (HiTrace_Output_Level level) 527``` 528**Description** 529Marks the end of a synchronous trace task with the trace output level specified. 530 531It must be used with **OH_HiTrace_StartTraceEx** in pairs. Its level must be the same as those of **OH_HiTrace_StartTraceEx**. 532 533During trace data parsing, the system matches it with the **OH_HiTrace_StartTraceEx** API recently invoked in the service process. 534 535 536 537**Since**: 19 538 539**Parameters** 540 541| Name| Description| 542| -------- | -------- | 543| level | Trace output level.| 544 545 546### OH_HiTrace_GetChainId() 547 548``` 549uint64_t OH_HiTrace_GetChainId (const HiTraceId * id) 550``` 551**Description** 552Obtains a trace chain ID. 553 554**System capability**: SystemCapability.HiviewDFX.HiTrace 555 556**Since**: 12 557 558**Parameters** 559 560| Name| Description| 561| -------- | -------- | 562| id | **HiTraceId** instance for which you want to obtain the trace chain ID. For details, see [HiTraceId](_hi_trace_id.md).| 563 564**Returns** 565 566Returns the trace chain ID of the specified **HiTraceId** instance. 567 568 569### OH_HiTrace_GetFlags() 570 571``` 572int OH_HiTrace_GetFlags (const HiTraceId * id) 573``` 574**Description** 575Obtains the trace flags in a **HiTraceId** instance. 576 577**System capability**: SystemCapability.HiviewDFX.HiTrace 578 579**Since**: 12 580 581**Parameters** 582 583| Name| Description| 584| -------- | -------- | 585| id | **HiTraceId** instance for which you want to obtain the flag. For details, see [HiTraceId](_hi_trace_id.md).| 586 587**Returns** 588 589Returns the trace flags set in the specified **HiTraceId** instance. 590 591 592### OH_HiTrace_GetId() 593 594``` 595HiTraceId OH_HiTrace_GetId () 596``` 597**Description** 598Obtains the trace ID of the calling thread. If the calling thread does not have a trace ID, an invalid trace ID is returned. 599 600Obtains the trace ID in TLS of the calling thread. 601 602**System capability**: SystemCapability.HiviewDFX.HiTrace 603 604**Since**: 12 605 606**Returns** 607 608Returns the [HiTraceId](_hi_trace_id.md) of the calling thread. Returns an invalid **HiTraceId** if the calling thread does not have a **HiTraceId**. 609 610 611### OH_HiTrace_GetParentSpanId() 612 613``` 614uint64_t OH_HiTrace_GetParentSpanId (const HiTraceId * id) 615``` 616**Description** 617Obtains the parent span ID in a **HiTraceId** instance. 618 619**System capability**: SystemCapability.HiviewDFX.HiTrace 620 621**Since**: 12 622 623**Parameters** 624 625| Name| Description| 626| -------- | -------- | 627| id | **HiTraceId** instance for which you want to obtain the parent span ID. For details, see [HiTraceId](_hi_trace_id.md).| 628 629**Returns** 630 631Returns the parent span ID in the specified **HiTraceId** instance. 632 633 634### OH_HiTrace_GetSpanId() 635 636``` 637uint64_t OH_HiTrace_GetSpanId (const HiTraceId * id) 638``` 639**Description** 640Obtains the span ID in a **HiTraceId** instance. 641 642**System capability**: SystemCapability.HiviewDFX.HiTrace 643 644**Since**: 12 645 646**Parameters** 647 648| Name| Description| 649| -------- | -------- | 650| id | **HiTraceId** instance for which you want to obtain the span ID. For details, see [HiTraceId](_hi_trace_id.md).| 651 652**Returns** 653 654Returns the span ID in the specified **HiTraceId** instance. 655 656 657### OH_HiTrace_IdFromBytes() 658 659``` 660void OH_HiTrace_IdFromBytes (HiTraceId * id, const uint8_t * pIdArray, int len ) 661``` 662**Description** 663Creates a **HiTraceId** instance based on a byte array. 664 665**System capability**: SystemCapability.HiviewDFX.HiTrace 666 667**Since**: 12 668 669**Parameters** 670 671| Name| Description| 672| -------- | -------- | 673| id | **[HiTraceId](_hi_trace_id.md)** instance to create. | 674| pIdArray | Byte array. | 675| len | Length of the byte array.| 676 677 678### OH_HiTrace_IdToBytes() 679 680``` 681int OH_HiTrace_IdToBytes (const HiTraceId * id, uint8_t * pIdArray, int len ) 682``` 683**Description** 684Converts a **HiTraceId** instance into a byte array for caching or transfer. 685 686**System capability**: SystemCapability.HiviewDFX.HiTrace 687 688**Since**: 12 689 690**Parameters** 691 692| Name| Description| 693| -------- | -------- | 694| id | **HiTraceId** instance to convert. For details, see [HiTraceId](_hi_trace_id.md). | 695| pIdArray | Byte array. | 696| len | Length of the byte array.| 697 698**Returns** 699 700Returns the length of the byte array after conversion. 701 702 703### OH_HiTrace_InitId() 704 705``` 706void OH_HiTrace_InitId (HiTraceId * id) 707``` 708**Description** 709Initializes a **HiTraceId** instance. 710 711**System capability**: SystemCapability.HiviewDFX.HiTrace 712 713**Since**: 12 714 715**Parameters** 716 717| Name| Description| 718| -------- | -------- | 719| id | **[HiTraceId](_hi_trace_id.md)** instance to initialize.| 720 721 722### OH_HiTrace_IsFlagEnabled() 723 724``` 725bool OH_HiTrace_IsFlagEnabled (const HiTraceId * id, HiTrace_Flag flag ) 726``` 727**Description** 728Checks whether the specified trace flag is enabled in a **HiTraceId** instance. 729 730 731 732**System capability**: SystemCapability.HiviewDFX.HiTrace 733 734**Since**: 12 735 736**Parameters** 737 738| Name| Description| 739| -------- | -------- | 740| id | **HiTraceId** instance to check. For details, see [HiTraceId](_hi_trace_id.md). | 741| flag | Specified trace flag. For details, see [HiTrace_Flag](#hitrace_flag). | 742 743**Returns** 744 745Returns **true** if the specified trace flag is enabled; returns **false** otherwise. 746 747 748### OH_HiTrace_IsIdValid() 749 750``` 751bool OH_HiTrace_IsIdValid (const HiTraceId * id) 752``` 753**Description** 754Checks whether a **HiTraceId** instance is valid. 755 756 757 758**System capability**: SystemCapability.HiviewDFX.HiTrace 759 760**Since**: 12 761 762**Parameters** 763 764| Name| Description| 765| -------- | -------- | 766| id | **HiTraceId** instance to check. For details, see [HiTraceId](_hi_trace_id.md). | 767 768**Returns** 769 770Returns **true** if the **HiTraceId** instance is valid; returns **false** otherwise. 771 772 773### OH_HiTrace_IsTraceEnabled() 774 775``` 776bool OH_HiTrace_IsTraceEnabled (void ) 777``` 778**Description** 779Checks whether trace capture is enabled for an application. If not, HiTraceMeter performance tracing is invalid. 780 781 782 783**Since**: 19 784 785**Returns** 786 787Returns **true** if the application trace capture is enabled and the HiTraceMeter performance tracing takes effect; 788 789returns **false** otherwise. 790 791 792### OH_HiTrace_SetChainId() 793 794``` 795void OH_HiTrace_SetChainId (HiTraceId * id, uint64_t chainId ) 796``` 797**Description** 798Sets the trace chain ID in a **HiTraceId** instance. 799 800**System capability**: SystemCapability.HiviewDFX.HiTrace 801 802**Since**: 12 803 804**Parameters** 805 806| Name| Description| 807| -------- | -------- | 808| id | **HiTraceId** instance. For details, see [HiTraceId](_hi_trace_id.md). | 809| chainId | Trace chain ID to set.| 810 811 812### OH_HiTrace_SetFlags() 813 814``` 815void OH_HiTrace_SetFlags (HiTraceId * id, int flags ) 816``` 817**Description** 818Sets trace flags in a **HiTraceId** instance. 819 820**System capability**: SystemCapability.HiviewDFX.HiTrace 821 822**Since**: 12 823 824**Parameters** 825 826| Name| Description| 827| -------- | -------- | 828| id | **HiTraceId** instance. For details, see [HiTraceId](_hi_trace_id.md). | 829| flags | Trace flag to set. For details, see [HiTrace_Flag](#hitrace_flag).| 830 831 832### OH_HiTrace_SetId() 833 834``` 835void OH_HiTrace_SetId (const HiTraceId * id) 836``` 837**Description** 838Sets the trace ID of the calling thread. If the ID is invalid, no operation is performed. 839 840This API sets a **HiTraceId** instance to the TLS of the calling thread. 841 842**System capability**: SystemCapability.HiviewDFX.HiTrace 843 844**Since**: 12 845 846**Parameters** 847 848| Name| Description| 849| -------- | -------- | 850| id | Trace ID of the calling thread. For details, see [HiTraceId](_hi_trace_id.md). | 851 852 853### OH_HiTrace_SetParentSpanId() 854 855``` 856void OH_HiTrace_SetParentSpanId (HiTraceId * id, uint64_t parentSpanId ) 857``` 858**Description** 859Sets the **ParentSpanId** in a **HiTraceId** instance. 860 861**System capability**: SystemCapability.HiviewDFX.HiTrace 862 863**Since**: 12 864 865**Parameters** 866 867| Name| Description| 868| -------- | -------- | 869| id | **HiTraceId** instance. For details, see [HiTraceId](_hi_trace_id.md). | 870| parentSpanId | Parent span ID to set.| 871 872 873### OH_HiTrace_SetSpanId() 874 875``` 876void OH_HiTrace_SetSpanId (HiTraceId * id, uint64_t spanId ) 877``` 878**Description** 879Sets the span ID in a **HiTraceId** instance. 880 881**System capability**: SystemCapability.HiviewDFX.HiTrace 882 883**Since**: 12 884 885**Parameters** 886 887| Name| Description| 888| -------- | -------- | 889| id | **HiTraceId** instance for which you want to set the span ID. | 890| spanId | Span ID to set.| 891 892 893### OH_HiTrace_StartAsyncTrace() 894 895``` 896void OH_HiTrace_StartAsyncTrace (const char * name, int32_t taskId ) 897``` 898**Description** 899Marks the start of an asynchronous trace. 900 901This API is used to start tracing before an asynchronous operation. The start and end of an asynchronous trace do not occur in sequence. Therefore, a unique task ID is required to identify them. 902 903It must be used with **OH_HiTrace_FinishAsyncTrace** in pairs. The start and end identified by the same name and task ID constitute an asynchronous trace task. 904 905If 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. 906 907If the trace tasks with the same name are not performed at the same time, the same taskId can be used. 908 909Since API version 19, you are advised to use the **OH_HiTrace_StartAsyncTraceEx** API to specify the trace output level and category. 910 911**System capability**: SystemCapability.HiviewDFX.HiTrace 912 913**Since**: 10 914 915**Parameters** 916 917| Name| Description| 918| -------- | -------- | 919| name | Name of the asynchronous trace. | 920| 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.| 921 922 923### OH_HiTrace_StartAsyncTraceEx() 924 925``` 926void OH_HiTrace_StartAsyncTraceEx (HiTrace_Output_Level level, const char * name, int32_t taskId, const char * customCategory, const char * customArgs ) 927``` 928**Description** 929Marks the start of an asynchronous trace task with the trace output level specified. 930 931This API is used to start tracing before an asynchronous operation. The start and end of an asynchronous trace do not occur in sequence. Therefore, a unique task ID is required to identify them. 932 933It is used with **OH_HiTrace_FinishAsyncTraceEx** in pairs. The start and end identified by the same name and task ID constitute an asynchronous trace task. 934 935If 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. 936 937If the trace tasks with the same name are not performed at the same time, the same **taskId** can be used. 938 939Task IDs of different processes does not interfere with each other. 940 941 942 943**Since**: 19 944 945**Parameters** 946 947| Name| Description| 948| -------- | -------- | 949| level | Trace output level. | 950| name | Name of the asynchronous trace. | 951| taskId | ID of the asynchronous trace. | 952| customCategory | Custom category name, which is used to collect asynchronous trace data of the same type. | 953| customArgs | Key-value pair. Use commas (,) to separate multiple key-value pairs, for example, "key1=value1,key2=value2".| 954 955 956### OH_HiTrace_StartTrace() 957 958``` 959void OH_HiTrace_StartTrace (const char * name) 960``` 961**Description** 962Marks the start of a synchronous trace. 963 964This API is used with **OH_HiTrace_FinishTrace** in pairs. 965 966The two APIs can be nested. The stack data structure is used for matching during trace parsing. 967 968Since API version 19, you are advised to use the **OH_HiTrace_StartTraceEx** API to specify the trace output level. 969 970**System capability**: SystemCapability.HiviewDFX.HiTrace 971 972**Since**: 10 973 974**Parameters** 975 976| Name| Description| 977| -------- | -------- | 978| name | Name of a synchronous trace.| 979 980 981### OH_HiTrace_StartTraceEx() 982 983``` 984void OH_HiTrace_StartTraceEx (HiTrace_Output_Level level, const char * name, const char * customArgs ) 985``` 986**Description** 987Marks the start of a synchronous trace task with the trace output level specified. 988 989This API is used with **OH_HiTrace_FinishTraceEx** in pairs. 990 991The two APIs can be nested. The stack data structure is used for matching during trace parsing. 992 993 994 995**Since**: 19 996 997**Parameters** 998 999| Name| Description| 1000| -------- | -------- | 1001| level | Trace output level. | 1002| name | Name of a synchronous trace. | 1003| customArgs | Key-value pair. Use commas (,) to separate multiple key-value pairs, for example, "key1=value1,key2=value2".| 1004 1005 1006### OH_HiTrace_Tracepoint() 1007 1008``` 1009void OH_HiTrace_Tracepoint (HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId * id, const char * fmt, ... ) 1010``` 1011**Description** 1012Prints HiTrace information, including the trace ID. 1013 1014This API prints trace point information, including the communication mode, trace point type, timestamp, and span. 1015 1016**System capability**: SystemCapability.HiviewDFX.HiTrace 1017 1018**Since**: 12 1019 1020**Parameters** 1021 1022| Name| Description| 1023| -------- | -------- | 1024| mode | Communication mode for the trace point. For details, see [HiTrace_Communication_Mode](#hitrace_communication_mode). | 1025| type | Trace point type. For details, see [HiTrace_Tracepoint_Type](#hitrace_tracepoint_type). | 1026| id | Trace ID. For details, see [HiTraceId](_hi_trace_id.md). | 1027| fmt | Custom information to print.| 1028 1029 1030## Variable Description 1031 1032 1033### chainId 1034 1035``` 1036uint64_t HiTraceId::chainId 1037``` 1038**Description** 1039Chain ID of **HiTraceId**. 1040 1041 1042### flags 1043 1044``` 1045uint64_t HiTraceId::flags 1046``` 1047**Description** 1048Flag of **HiTraceId**. 1049 1050 1051### parentSpanId 1052 1053``` 1054uint64_t HiTraceId::parentSpanId 1055``` 1056**Description** 1057Parent span ID of **HiTraceId**. 1058 1059 1060### spanId 1061 1062``` 1063uint64_t HiTraceId::spanId 1064``` 1065**Description** 1066Span ID of **HiTraceId**. 1067 1068 1069### valid 1070 1071``` 1072uint64_t HiTraceId::valid 1073``` 1074**Description** 1075Whether a **HiTraceId** instance is valid. 1076 1077 1078### ver 1079 1080``` 1081uint64_t HiTraceId::ver 1082``` 1083**Description** 1084Version number of **HiTraceId**. 1085