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