1# trace.h 2 3 4## Overview 5 6Defines APIs of the HiTraceMeter module for performance trace. 7 8 9The 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. 10 11The maximum length of a user-mode trace is 512 characters. Excess characters will be truncated. 12 13**Library**: libhitrace_ndk.z.so 14 15**File to include**: 16 17<hitrace/trace.h> 18 19**System capability**: SystemCapability.HiviewDFX.HiTrace 20 21**Since**: 10 22 23**Related module**: [HiTrace](_hitrace.md) 24 25 26## Summary 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](_hitrace.md#hitraceid_valid) [HiTraceId_Valid](_hitrace.md#hitraceid_valid) | Defines an enum for whether a **HiTraceId** instance is valid. | 41| typedef enum [HiTrace_Version](_hitrace.md#hitrace_version) [HiTrace_Version](_hitrace.md#hitrace_version) | Defines an enum for the HiTrace versions. | 42| typedef enum [HiTrace_Flag](_hitrace.md#hitrace_flag) [HiTrace_Flag](_hitrace.md#hitrace_flag) | Defines an enum for the HiTrace flags. | 43| typedef enum [HiTrace_Tracepoint_Type](_hitrace.md#hitrace_tracepoint_type) [HiTrace_Tracepoint_Type](_hitrace.md#hitrace_tracepoint_type) | Defines an enum for the HiTrace tracepoint types. | 44| typedef enum [HiTrace_Communication_Mode](_hitrace.md#hitrace_communication_mode) [HiTrace_Communication_Mode](_hitrace.md#hitrace_communication_mode) | Defines an enum for the HiTrace communication modes. | 45| typedef struct [HiTraceId](_hi_trace_id.md) [HiTraceId](_hi_trace_id.md) | Defines a struct for the HiTrace ID.| 46| typedef enum [HiTrace_Output_Level](_hitrace.md#hitrace_output_level) [HiTrace_Output_Level](_hitrace.md#hitrace_output_level) | Defines an enum for the HiTrace output levels. | 47 48 49### Enums 50 51| Name| Description| 52| -------- | -------- | 53| [HiTraceId_Valid](_hitrace.md#hitraceid_valid) { HITRACE_ID_INVALID = 0, HITRACE_ID_VALID = 1 } | Enumerates whether a **HiTraceId** instance is valid. | 54| [HiTrace_Version](_hitrace.md#hitrace_version) { HITRACE_VER_1 = 0 } | Enumerates the HiTrace versions. | 55| [HiTrace_Flag](_hitrace.md#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.md#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.md#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.md#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} | Enumerates the HiTrace output levels. | 59 60 61### Functions 62 63| Name| Description| 64| -------- | -------- | 65| [HiTraceId](_hi_trace_id.md) [OH_HiTrace_BeginChain](_hitrace.md#oh_hitrace_beginchain) (const char \*name, int flags) | Starts tracing a process. | 66| void [OH_HiTrace_EndChain](_hitrace.md#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](_hitrace.md#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](_hitrace.md#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](_hitrace.md#oh_hitrace_clearid) (void) | Clears the trace ID of the calling thread and invalidates it. | 70| [HiTraceId](_hi_trace_id.md) [OH_HiTrace_CreateSpan](_hitrace.md#oh_hitrace_createspan) (void) | Creates a span ID based on the trace ID of the calling thread. | 71| void [OH_HiTrace_Tracepoint](_hitrace.md#oh_hitrace_tracepoint) ([HiTrace_Communication_Mode](_hitrace.md#hitrace_communication_mode) mode, [HiTrace_Tracepoint_Type](_hitrace.md#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](_hitrace.md#oh_hitrace_initid) ([HiTraceId](_hi_trace_id.md) \*id) | Initializes a **HiTraceId** instance. | 73| void [OH_HiTrace_IdFromBytes](_hitrace.md#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](_hitrace.md#oh_hitrace_isidvalid) (const [HiTraceId](_hi_trace_id.md) \*id) | Checks whether a **HiTraceId** instance is valid. | 75| bool [OH_HiTrace_IsFlagEnabled](_hitrace.md#oh_hitrace_isflagenabled) (const [HiTraceId](_hi_trace_id.md) \*id, [HiTrace_Flag](_hitrace.md#hitrace_flag) flag) | Checks whether the specified trace flag is enabled in a **HiTraceId** instance. | 76| void [OH_HiTrace_EnableFlag](_hitrace.md#oh_hitrace_enableflag) (const [HiTraceId](_hi_trace_id.md) \*id, [HiTrace_Flag](_hitrace.md#hitrace_flag) flag) | Enables the specified trace flag in a **HiTraceId** instance. | 77| int [OH_HiTrace_GetFlags](_hitrace.md#oh_hitrace_getflags) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains the trace flags in a **HiTraceId** instance. | 78| void [OH_HiTrace_SetFlags](_hitrace.md#oh_hitrace_setflags) ([HiTraceId](_hi_trace_id.md) \*id, int flags) | Sets trace flags in a **HiTraceId** instance. | 79| uint64_t [OH_HiTrace_GetChainId](_hitrace.md#oh_hitrace_getchainid) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains a trace chain ID. | 80| void [OH_HiTrace_SetChainId](_hitrace.md#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](_hitrace.md#oh_hitrace_getspanid) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains the span ID in a **HiTraceId** instance. | 82| void [OH_HiTrace_SetSpanId](_hitrace.md#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](_hitrace.md#oh_hitrace_getparentspanid) (const [HiTraceId](_hi_trace_id.md) \*id) | Obtains the parent span ID in a **HiTraceId** instance. | 84| void [OH_HiTrace_SetParentSpanId](_hitrace.md#oh_hitrace_setparentspanid) ([HiTraceId](_hi_trace_id.md) \*id, uint64_t parentSpanId) | Sets the **ParentSpanId** in a **HiTraceId** instance. | 85| int [OH_HiTrace_IdToBytes](_hitrace.md#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](_hitrace.md#oh_hitrace_starttrace) (const char \*name) | Marks the start of a synchronous trace. | 87| void [OH_HiTrace_FinishTrace](_hitrace.md#oh_hitrace_finishtrace) (void) | Marks the end of a synchronous trace. | 88| void [OH_HiTrace_StartAsyncTrace](_hitrace.md#oh_hitrace_startasynctrace) (const char \*name, int32_t taskId) | Marks the start of an asynchronous trace. | 89| void [OH_HiTrace_FinishAsyncTrace](_hitrace.md#oh_hitrace_finishasynctrace) (const char \*name, int32_t taskId) | Marks the end of an asynchronous trace. | 90| void [OH_HiTrace_CountTrace](_hitrace.md#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](_hitrace.md#oh_hitrace_starttraceex) ([HiTrace_Output_Level](_hitrace.md#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](_hitrace.md#oh_hitrace_finishtraceex) ([HiTrace_Output_Level](_hitrace.md#hitrace_output_level) level) | Marks the end of a synchronous trace task with the trace output level specified. | 93| void [OH_HiTrace_StartAsyncTraceEx](_hitrace.md#oh_hitrace_startasynctraceex) ([HiTrace_Output_Level](_hitrace.md#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](_hitrace.md#oh_hitrace_finishasynctraceex) ([HiTrace_Output_Level](_hitrace.md#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](_hitrace.md#oh_hitrace_counttraceex) ([HiTrace_Output_Level](_hitrace.md#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](_hitrace.md#oh_hitrace_istraceenabled) (void) | Checks whether trace capture is enabled for an application. If not, HiTraceMeter performance tracing is invalid. | 97