trace.h
Overview
Defines APIs of the HiTraceMeter and HiTraceChain modules for performance tracing and distributed tracing.
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.
The maximum length of a user-mode trace is 512 characters. Excess characters will be truncated.
File to include: <hitrace/trace.h>
Library: libhitrace_ndk.z.so
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 10
Related module: HiTrace
Summary
Structs
| Name | typedef Keyword | Description |
|---|---|---|
| HiTraceId | HiTraceId | Defines a HiTraceId instance. |
Enums
| Name | typedef Keyword | Description |
|---|---|---|
| HiTraceId_Valid | HiTraceId_Valid | Enumerates whether a HiTraceId instance is valid. |
| HiTrace_Version | HiTrace_Version | Enumerates the HiTrace versions. |
| HiTrace_Flag | HiTrace_Flag | Enumerates the HiTrace flags. |
| HiTrace_Tracepoint_Type | HiTrace_Tracepoint_Type | Enumerates the trace point types. |
| HiTrace_Communication_Mode | HiTrace_Communication_Mode | Enumerates the trace communication types. |
| 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. |
Functions
| Name | typedef Keyword | Description |
|---|---|---|
| typedef void (*OH_HiTrace_TraceEventListener)(bool traceStatus) | OH_HiTrace_TraceEventListener | Defines a callback to listen for whether the trace capture is enabled. |
| HiTraceId OH_HiTrace_BeginChain(const char *name, int flags) | - | Starts tracing. If the current thread's TLS does not contain a valid HiTrace ID, this function generates one, stores it in TLS, and returns it. If the current thread's TLS already contains a valid HiTrace ID, this function does not start tracing and returns an invalid HiTrace ID with all property values being 0. |
| void OH_HiTrace_EndChain() | - | Stops tracing. Stops tracing and sets the HiTrace ID in the TLS of the current thread to invalid. |
| HiTraceId OH_HiTrace_GetId() | - | Obtains the HiTrace ID in the TLS of the current thread. |
| void OH_HiTrace_SetId(const HiTraceId *id) | - | Sets the given HiTrace ID to the TLS of the current thread. If the given HiTrace ID is invalid, no operation is performed. |
| void OH_HiTrace_ClearId(void) | - | Clears the HiTrace ID in the current thread's TLS. |
| HiTraceId OH_HiTrace_CreateSpan(void) | - | Creates a trace span. Specifically, create a HiTraceId, use the chainId and spanId in the TLS of the current thread to initialize the chainId and parentSpanId of the HiTraceId, generate a new spanId for the HiTraceId, and return the HiTraceId. |
| void OH_HiTrace_Tracepoint(HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId *id, const char *fmt, ...) | - | Adds a trace point for the HiTraceMeter logging. When type is set to HITRACE_TP_CS and HITRACE_TP_SR, the HiTraceMeter tracing starts. When type is set to HITRACE_TP_CR and HITRACE_TP_SS, the HiTraceMeter tracing ends. When type is set to HITRACE_TP_GENERAL, the HiTraceMeter tracing does not start. The tracing points of HITRACE_TP_CS and HITRACE_TP_CR must be used in pairs; the tracing points of HITRACE_TP_SR and HITRACE_TP_SS must be used in pairs. Otherwise, the start and end trace points of HiTraceMeter cannot match each other. |
| void OH_HiTrace_InitId(HiTraceId *id) | - | Initializes a HiTraceId. |
| void OH_HiTrace_IdFromBytes(HiTraceId *id, const uint8_t *pIdArray, int len) | - | Creates a HiTraceId based on a byte array. |
| bool OH_HiTrace_IsIdValid(const HiTraceId *id) | - | Checks whether the HiTraceId is valid. |
| bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag) | - | Checks whether the trace flag is enabled for the HiTraceId. |
| void OH_HiTrace_EnableFlag(const HiTraceId *id, HiTrace_Flag flag) | - | Enables the trace flag specified in HiTraceId. |
| int OH_HiTrace_GetFlags(const HiTraceId *id) | - | Obtains the trace flag set in HiTraceId. |
| void OH_HiTrace_SetFlags(HiTraceId *id, int flags) | - | Sets the trace flag to HiTraceId. |
| uint64_t OH_HiTrace_GetChainId(const HiTraceId *id) | - | Obtains the trace chain ID in HiTraceId. |
| void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId) | - | Sets the trace chain ID in HiTraceId. |
| uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id) | - | Obtains the span ID in HiTraceId. |
| void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId) | - | Sets the span ID in HiTraceId. |
| uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id) | - | Obtains the parent span ID in HiTraceId. |
| void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId) | - | Sets the ParentSpanId in a HiTraceId instance. |
| int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len) | - | Converts HiTraceId into a byte array for cache or communication. |
| void OH_HiTrace_StartTrace(const char *name) | - | Marks the start of a synchronous trace. This API is used with OH_HiTrace_FinishTrace() in pairs. The two APIs can be nested. The stack data structure is used for matching during trace parsing. Since API version 19, you are advised to use the OH_HiTrace_StartTraceEx() API to specify the trace output level. |
| void OH_HiTrace_FinishTrace(void) | - | 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 latest OH_HiTrace_StartTrace() API in the service process. Since API version 19, you are advised to use the OH_HiTrace_FinishTraceEx() API to specify the trace output level. |
| void OH_HiTrace_StartAsyncTrace(const char *name, int32_t taskId) | - | 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. 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. 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. If the trace tasks with the same name are not performed at the same time, the same taskId can be used. Since API version 19, you are advised to use the OH_HiTrace_StartAsyncTraceEx() API to specify the trace output level and category. |
| void OH_HiTrace_FinishAsyncTrace(const char *name, int32_t taskId) | - | Marks the end of an asynchronous trace. This 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(). Since API version 19, you are advised to use the OH_HiTrace_FinishAsyncTraceEx() API to specify the trace output level. |
| void OH_HiTrace_CountTrace(const char *name, int64_t count) | - | 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. Since API version 19, you are advised to use the OH_HiTrace_CountTraceEx() API to specify the trace output level. |
| void OH_HiTrace_StartTraceEx(HiTrace_Output_Level level, const char *name, const char *customArgs) | - | Marks the start of a synchronous trace task with the trace output level specified. This API is used with OH_HiTrace_FinishTraceEx() in pairs. The two APIs can be nested. The stack data structure is used for matching during trace parsing. |
| void OH_HiTrace_FinishTraceEx(HiTrace_Output_Level level) | - | 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(). During trace data parsing, the system matches it with the OH_HiTrace_StartTraceEx() API recently invoked in the service process. |
| void OH_HiTrace_StartAsyncTraceEx(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. 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. 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. 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. If the trace tasks with the same name are not performed at the same time, the same taskId can be used. Task IDs of different processes does not interfere with each other. |
| void OH_HiTrace_FinishAsyncTraceEx(HiTrace_Output_Level level, const char *name, int32_t taskId) | - | 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. 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(). |
| void OH_HiTrace_CountTraceEx(HiTrace_Output_Level level, const char *name, int64_t count) | - | Marks an integer variable trace task with the trace output level specified. |
| bool OH_HiTrace_IsTraceEnabled(void) | - | Checks whether trace capture is enabled for an application. |
| int32_t OH_HiTrace_RegisterTraceListener(OH_HiTrace_TraceEventListener callback) | - | Registers a callback to notify whether the application trace capture is enabled. This API uses a synchronous callback to return the result. After the registration is successful, the callback is executed immediately. Subsequent callbacks are executed when the application trace capture status changes. Callbacks are stored in the application process. A maximum of 10 callbacks can be registered in a process. If the callback contains time-consuming operations, the registration or unregistration will be blocked (waiting for the callback execution to complete) when the callback is executed. Therefore, you are advised not to register or unregister callbacks containing time-consuming operations in the main thread of the application to avoid application freeze. |
| int32_t OH_HiTrace_UnregisterTraceListener(int32_t index) | - | Unregisters the callback used to notify whether the application trace capture is enabled. You can use this function to unregister the callback function associated with the callback index returned by OH_HiTrace_RegisterTraceListener. |
Enum Description
HiTraceId_Valid
enum HiTraceId_Valid
Description
Enumerates whether a HiTraceId instance is valid.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
| Enum Item | Description |
|---|---|
| HITRACE_ID_INVALID = 0 | Invalid HiTraceId. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_ID_VALID = 1 | Valid HiTraceId. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
HiTrace_Version
enum HiTrace_Version
Description
Enumerates the HiTrace versions.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
| Enum Item | Description |
|---|---|
| HITRACE_VER_1 = 0 | Version 1. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
HiTrace_Flag
enum HiTrace_Flag
Description
Enumerates the HiTrace flags.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
| Enum Item | Description |
|---|---|
| HITRACE_FLAG_DEFAULT = 0 | Default flag. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_INCLUDE_ASYNC = 1 << 0 | Asynchronous call flag. When this flag is set, both synchronous and asynchronous calls are traced. By default, only synchronous calls are traced. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_DONOT_CREATE_SPAN = 1 << 1 | No span flag. When this flag is set, no span information is created. By default, span information is created. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_TP_INFO = 1 << 2 | Trace point flag. When this flag is set in the debugging scenario, the HiLog logs of the trace point are printed upon calling the OH_HiTrace_Tracepoint() API. By default, the HiLog logs are not printed. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_NO_BE_INFO = 1 << 3 | No begin and end flag. When this flag is set in the debugging scenario, the HiLog logs about the begin and end of tracing are printed when the OH_HiTrace_BeginChain() and OH_HiTrace_EndChain() APIs are called. By default, the HiLog logs about the begin and end of tracing are not printed. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_DONOT_ENABLE_LOG = 1 << 4 | Log association flag. When this flag is set, the HiTraceId information is not added to the HiLog logs. By default, the HiTraceId information is added to the HiLog logs. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_FAULT_TRIGGER = 1 << 5 | Failure trigger flag. This is a reserved flag. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_FLAG_D2D_TP_INFO = 1 << 6 | Device-to-device trace point flag. It is a subset of HITRACE_FLAG_TP_INFO and is used in debugging scenarios. When the HITRACE_FLAG_TP_INFO flag is set, the HITRACE_FLAG_D2D_TP_INFO flag does not take effect. When HITRACE_FLAG_TP_INFO is not set and HITRACE_FLAG_D2D_TP_INFO is set, the HiLog logs of the trace point are printed only when the mode parameter is set to HITRACE_CM_DEVICE upon calling OH_HiTrace_Tracepoint(). Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
HiTrace_Tracepoint_Type
enum HiTrace_Tracepoint_Type
Description
Enumerates the trace point types.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
| Enum Item | Description |
|---|---|
| HITRACE_TP_CS = 0 | CS trace point. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_TP_CR = 1 | CR trace point. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_TP_SS = 2 | SS trace point. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_TP_SR = 3 | SR trace point. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_TP_GENERAL = 4 | General type, which identifies the trace points except HITRACE_TP_CS, HITRACE_TP_CR, HITRACE_TP_SS, and HITRACE_TP_SR. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
HiTrace_Communication_Mode
enum HiTrace_Communication_Mode
Description
Enumerates the trace communication types.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
| Enum Item | Description |
|---|---|
| HITRACE_CM_DEFAULT = 0 | Default communication. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_CM_THREAD = 1 | Inter-thread communication. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_CM_PROCESS = 2 | Inter-process communication (IPC). Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
| HITRACE_CM_DEVICE = 3 | Inter-device communication. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
HiTrace_Output_Level
enum HiTrace_Output_Level
Description
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.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 19
| Enum Item | Description |
|---|---|
| HITRACE_LEVEL_DEBUG = 0 | Level used only for debugging, which has the lowest priority. Since: 19 |
| HITRACE_LEVEL_INFO = 1 | Level for the log version. Since: 19 |
| HITRACE_LEVEL_CRITICAL = 2 | Level for the log version, which has a higher priority than INFO. Since: 19 |
| HITRACE_LEVEL_COMMERCIAL = 3 | Level for the nolog version, which has the highest priority. Since: 19 |
| HITRACE_LEVEL_MAX = HITRACE_LEVEL_COMMERCIAL | The maximum output level. Since: 19 |
Function Description
OH_HiTrace_TraceEventListener()
typedef void (*OH_HiTrace_TraceEventListener)(bool traceStatus)
Description
Defines a callback to listen for whether the trace capture is enabled.
Since: 22
Parameters
| Name | Description |
|---|---|
| bool traceStatus | Whether the trace capture is enabled for the current application. The value true indicates that the trace capture is enabled, and false indicates the opposite. |
OH_HiTrace_BeginChain()
HiTraceId OH_HiTrace_BeginChain(const char *name, int flags)
Description
Starts tracing.
If the current thread's TLS does not contain a valid HiTrace ID, this function generates one, stores it in TLS, and returns it.
If the current thread's TLS already contains a valid HiTrace ID, this function does not start tracing and returns an invalid HiTrace ID with all property values being 0.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const char *name | Name of the traced service. |
| int flags | Trace flags. For details, see HiTrace_Flag. |
Returns
| Type | Description |
|---|---|
| HiTraceId | The HiTraceId struct. |
OH_HiTrace_EndChain()
void OH_HiTrace_EndChain()
Description
Stops tracing.
Stops tracing and sets the HiTrace ID in the TLS of the current thread to invalid.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
OH_HiTrace_GetId()
HiTraceId OH_HiTrace_GetId()
Description
Obtains the HiTrace ID in the TLS of the current thread.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Returns
| Type | Description |
|---|---|
| HiTraceId | The HiTraceId struct. |
OH_HiTrace_SetId()
void OH_HiTrace_SetId(const HiTraceId *id)
Description
Sets the given HiTrace ID to the TLS of the current thread. If the given HiTrace ID is invalid, no operation is performed.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const HiTraceId *id | HiTraceId to set. |
OH_HiTrace_ClearId()
void OH_HiTrace_ClearId(void)
Description
Clears the HiTrace ID in the current thread's TLS.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
OH_HiTrace_CreateSpan()
HiTraceId OH_HiTrace_CreateSpan(void)
Description
Creates a trace span.
Specifically, create a HiTraceId, use the chainId and spanId in the TLS of the current thread to initialize the chainId and parentSpanId of the HiTraceId, generate a new spanId for the HiTraceId, and return the HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Returns
| Type | Description |
|---|---|
| HiTraceId | The HiTraceId struct. |
OH_HiTrace_Tracepoint()
void OH_HiTrace_Tracepoint(HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId *id, const char *fmt, ...)
Description
Adds a trace point for the HiTraceMeter logging.
When type is set to HITRACE_TP_CS and HITRACE_TP_SR, the HiTraceMeter tracing starts. When type is set to HITRACE_TP_CR and HITRACE_TP_SS, the HiTraceMeter tracing ends. When type is set to HITRACE_TP_GENERAL, the HiTraceMeter tracing does not start.
The tracing points of HITRACE_TP_CS and HITRACE_TP_CR must be used in pairs; the tracing points of HITRACE_TP_SR and HITRACE_TP_SS must be used in pairs. Otherwise, the start and end trace points of HiTraceMeter cannot match each other.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| HiTrace_Communication_Mode mode | Trace communication mode. For details, see HiTrace_Communication_Mode. |
| HiTrace_Tracepoint_Type type | Trace information type. For details, see HiTrace_Tracepoint_Type. |
| const HiTraceId *id | HiTraceId for implementing trace points. |
| const char *fmt | Formatted string of the trace description information passed by the HiTraceMeter logging. |
OH_HiTrace_InitId()
void OH_HiTrace_InitId(HiTraceId *id)
Description
Initializes a HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| HiTraceId *id | HiTraceId to initialize. |
OH_HiTrace_IdFromBytes()
void OH_HiTrace_IdFromBytes(HiTraceId *id, const uint8_t *pIdArray, int len)
Description
Creates a HiTraceId based on a byte array.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| HiTraceId *id | HiTraceId to create. |
| const uint8_t *pIdArray | Byte array. |
| int len | Length of the byte array. |
OH_HiTrace_IsIdValid()
bool OH_HiTrace_IsIdValid(const HiTraceId *id)
Description
Checks whether the HiTraceId is valid.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const HiTraceId *id | HiTraceId to check. |
Returns
| Type | Description |
|---|---|
| bool | The value true indicates that HiTraceId is valid, and false indicates the opposite. |
OH_HiTrace_IsFlagEnabled()
bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag)
Description
Checks whether the trace flag is enabled for the HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const HiTraceId *id | HiTraceId to check. |
| HiTrace_Flag flag | Trace flag. For details, see HiTrace_Flag. |
Returns
| Type | Description |
|---|---|
| bool | The value true indicates that the flag is enabled for the HiTraceId, and false indicates the opposite. |
OH_HiTrace_EnableFlag()
void OH_HiTrace_EnableFlag(const HiTraceId *id, HiTrace_Flag flag)
Description
Enables the trace flag specified in HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const HiTraceId *id | HiTraceId for which the trace flag is enabled. |
| HiTrace_Flag flag | Trace flag. For details, see HiTrace_Flag. |
OH_HiTrace_GetFlags()
int OH_HiTrace_GetFlags(const HiTraceId *id)
Description
Obtains the trace flag set in HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const HiTraceId *id | HiTraceId for which the trace flag is obtained. |
Returns
| Type | Description |
|---|---|
| int | Trace flag set in HiTraceId. |
OH_HiTrace_SetFlags()
void OH_HiTrace_SetFlags(HiTraceId *id, int flags)
Description
Sets the trace flag to HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| HiTraceId *id | HiTraceId to which the trace flag is set. |
| int flags | Trace flag. For details, see HiTrace_Flag. |
OH_HiTrace_GetChainId()
uint64_t OH_HiTrace_GetChainId(const HiTraceId *id)
Description
Obtains the trace chain ID in HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const HiTraceId *id | HiTraceId for which the trace chain ID is obtained. |
Returns
| Type | Description |
|---|---|
| uint64_t | Trace chain ID. |
OH_HiTrace_SetChainId()
void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId)
Description
Sets the trace chain ID in HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| HiTraceId *id | HiTraceId to which the trace chain ID is to be set. |
| uint64_t chainId | Trace chain ID to set. |
OH_HiTrace_GetSpanId()
uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id)
Description
Obtains the span ID in HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const HiTraceId *id | HiTraceId for which span ID is obtained. |
Returns
| Type | Description |
|---|---|
| uint64_t | Span ID set in HiTraceId. |
OH_HiTrace_SetSpanId()
void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId)
Description
Sets the span ID in HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| HiTraceId *id | HiTraceId to which the span ID is set. |
| uint64_t spanId | Span ID to set. |
OH_HiTrace_GetParentSpanId()
uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id)
Description
Obtains the parent span ID in HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const HiTraceId *id | HiTraceId for which the parent span ID is obtained. |
Returns
| Type | Description |
|---|---|
| uint64_t | Parent span ID set in HiTraceId. |
OH_HiTrace_SetParentSpanId()
void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId)
Description
Sets the ParentSpanId in a HiTraceId instance.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| HiTraceId *id | HiTraceId to which the parent span ID is set. |
| uint64_t parentSpanId | Parent span ID to set. |
OH_HiTrace_IdToBytes()
int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len)
Description
Converts HiTraceId into a byte array for cache or communication.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const HiTraceId* id | HiTraceId to convert. |
| uint8_t* pIdArray | Byte array. |
| int len | Length of the byte array. |
Returns
| Type | Description |
|---|---|
| int | Returns the length of the byte array after conversion. |
OH_HiTrace_StartTrace()
void OH_HiTrace_StartTrace(const char *name)
Description
Marks the start of a synchronous trace.
This API is used with OH_HiTrace_FinishTrace() in pairs.
The two APIs can be nested. The stack data structure is used for matching during trace parsing.
Since API version 19, you are advised to use the OH_HiTrace_StartTraceEx() API to specify the trace output level.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 10
Parameters
| Name | Description |
|---|---|
| const char *name | Name of a synchronous trace. |
OH_HiTrace_FinishTrace()
void OH_HiTrace_FinishTrace(void)
Description
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 latest OH_HiTrace_StartTrace() API in the service process.
Since API version 19, you are advised to use the OH_HiTrace_FinishTraceEx() API to specify the trace output level.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 10
OH_HiTrace_StartAsyncTrace()
void OH_HiTrace_StartAsyncTrace(const char *name, int32_t taskId)
Description
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.
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.
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.
If the trace tasks with the same name are not performed at the same time, the same taskId can be used.
Since API version 19, you are advised to use the OH_HiTrace_StartAsyncTraceEx() API to specify the trace output level and category.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 10
Parameters
| Name | Description |
|---|---|
| const char *name | Name of the asynchronous trace. |
| int32_t taskId | ID of the asynchronous trace. The start and end of an asynchronous trace 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. |
OH_HiTrace_FinishAsyncTrace()
void OH_HiTrace_FinishAsyncTrace(const char *name, int32_t taskId)
Description
Marks the end of an asynchronous trace.
This 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().
Since API version 19, you are advised to use the OH_HiTrace_FinishAsyncTraceEx() API to specify the trace output level.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 10
Parameters
| Name | Description |
|---|---|
| const char *name | Name of the asynchronous trace. |
| int32_t taskId | ID of the asynchronous trace. The start and end of an asynchronous trace 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. |
OH_HiTrace_CountTrace()
void OH_HiTrace_CountTrace(const char *name, int64_t count)
Description
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.
Since API version 19, you are advised to use the OH_HiTrace_CountTraceEx() API to specify the trace output level.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 10
Parameters
| Name | Description |
|---|---|
| const char *name | Name of the integer variable. It does not need to be the same as the real variable name. |
| int64_t count | Integer value. |
OH_HiTrace_StartTraceEx()
void OH_HiTrace_StartTraceEx(HiTrace_Output_Level level, const char *name, const char *customArgs)
Description
Marks the start of a synchronous trace task with the trace output level specified.
This API is used with OH_HiTrace_FinishTraceEx() in pairs.
The two APIs can be nested. The stack data structure is used for matching during trace parsing.
Since: 19
Parameters
| Name | Description |
|---|---|
| HiTrace_Output_Level level | Trace output level. |
| const char *name | Name of a synchronous trace. |
| const char *customArgs | Key-value pair. Use commas (,) to separate multiple key-value pairs, for example, "key1=value1,key2=value2". |
OH_HiTrace_FinishTraceEx()
void OH_HiTrace_FinishTraceEx(HiTrace_Output_Level level)
Description
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().
During trace data parsing, the system matches it with the OH_HiTrace_StartTraceEx() API recently invoked in the service process.
Since: 19
Parameters
| Name | Description |
|---|---|
| HiTrace_Output_Level level | Trace output level. |
OH_HiTrace_StartAsyncTraceEx()
void OH_HiTrace_StartAsyncTraceEx(HiTrace_Output_Level level, const char *name, int32_t taskId, const char *customCategory, const char *customArgs)
Description
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.
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.
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.
If the trace tasks with the same name are not performed at the same time, the same taskId can be used.
Task IDs of different processes does not interfere with each other.
Since: 19
Parameters
| Name | Description |
|---|---|
| HiTrace_Output_Level level | Trace output level. |
| const char *name | Name of the asynchronous trace. |
| int32_t taskId | ID of the asynchronous trace. |
| const char *customCategory | Custom category name, which is used to collect asynchronous trace data of the same type. |
| const char *customArgs | Key-value pair. Use commas (,) to separate multiple key-value pairs, for example, "key1=value1,key2=value2". |
OH_HiTrace_FinishAsyncTraceEx()
void OH_HiTrace_FinishAsyncTraceEx(HiTrace_Output_Level level, const char *name, int32_t taskId)
Description
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.
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().
Since: 19
Parameters
| Name | Description |
|---|---|
| HiTrace_Output_Level level | Trace output level. |
| const char *name | Name of the asynchronous trace. |
| int32_t taskId | ID of the asynchronous trace. |
OH_HiTrace_CountTraceEx()
void OH_HiTrace_CountTraceEx(HiTrace_Output_Level level, const char *name, int64_t count)
Description
Marks an integer variable trace task with the trace output level specified.
Since: 19
Parameters
| Name | Description |
|---|---|
| HiTrace_Output_Level level | Trace output level. |
| const char *name | Name of the integer variable. It does not need to be the same as the actual variable name. |
| int64_t count | Integer value. |
OH_HiTrace_IsTraceEnabled()
bool OH_HiTrace_IsTraceEnabled(void)
Description
Checks whether trace capture is enabled for an application.
Since: 19
Returns
| Type | Description |
|---|---|
| bool | When it is enabled, true is returned; when it is disabled or stopped, false is returned. In this case, calling the HiTraceMeter API does not take effect. |
OH_HiTrace_RegisterTraceListener()
int32_t OH_HiTrace_RegisterTraceListener(OH_HiTrace_TraceEventListener callback)
Description
Registers a callback to notify whether the application trace capture is enabled. This API uses a synchronous callback to return the result.
After the registration is successful, the callback is executed immediately. Subsequent callbacks are executed when the application trace capture status changes.
Callbacks are stored in the application process. A maximum of 10 callbacks can be registered in a process.
If the callback contains time-consuming operations, the registration or unregistration will be blocked (waiting for the callback execution to complete) when the callback is executed.
Therefore, you are advised not to register or unregister callbacks containing time-consuming operations in the main thread of the application to avoid application freeze.
Since: 22
Parameters
| Name | Description |
|---|---|
| OH_HiTrace_TraceEventListener callback | Registered callback. |
Returns
| Type | Description |
|---|---|
| int32_t | Callback registration status. >= 0: The registration is successful. The callback index for unregistration is returned. The index ranges from 0 to 9. -1: The maximum number of callbacks has been reached. -2: Invalid parameter. The parameter is not of the TraceEventListener type. |
OH_HiTrace_UnregisterTraceListener()
int32_t OH_HiTrace_UnregisterTraceListener(int32_t index)
Description
Unregisters the callback used to notify whether the application trace capture is enabled.
You can use this function to unregister the callback function associated with the callback index returned by OH_HiTrace_RegisterTraceListener.
Since: 22
Parameters
| Name | Description |
|---|---|
| int32_t index | Index of the registered callback. |
Returns
| Type | Description |
|---|---|
| int32_t | Callback unregistration status. 0: Unregistration succeeded. -1: The callback corresponding to the index is not registered. -2: Invalid index. The index value is not within the range of 0 to 9. |