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
| 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 threshold for the log version is HITRACE_LEVEL_INFO, and that for the no-log version is HITRACE_LEVEL_COMMERCIAL. |
| 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 HiTraceId in the TLS of the current thread. |
| void OH_HiTrace_SetId(const HiTraceId *id) | - | Sets the given HiTraceId to the TLS of the current thread. If the input parameter is invalid, no operation is performed. |
| void OH_HiTrace_ClearId(void) | - | Sets the HiTraceId in the TLS of the current thread to invalid. |
| HiTraceId OH_HiTrace_CreateSpan(void) | - | Creates a trace span. Creates a HiTraceId, uses the chainId and spanId in the TLS of the current thread to initialize its chainId and parentSpanId, and generates a new spanId for it. |
| 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 (client sending) or HITRACE_TP_SR (server receiving), the synchronous HiTraceMeter logging starts. When type is set to HITRACE_TP_CR (client receiving) or HITRACE_TP_SS (server sending), the synchronous HiTraceMeter logging ends. When type is set to HITRACE_TP_GENERAL, HiTraceMeter logging is not performed. The trace points must be used in pairs: HITRACE_TP_CS with HITRACE_TP_CR, and HITRACE_TP_SR with HITRACE_TP_SS. 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 a HiTraceId is valid. |
| bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag) | - | Checks whether a trace flag is enabled for a 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 from HiTraceId. |
| void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId) | - | Sets the trace chain ID to HiTraceId. |
| uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id) | - | Obtains the span ID from the current HiTraceId. |
| void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId) | - | Sets the span ID to HiTraceId. |
| uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id) | - | Obtains the parent span ID from the current HiTraceId. |
| void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId) | - | Sets the parentSpanId field in the HiTraceId struct. |
| int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len) | - | Converts a HiTraceId to a byte array for caching or communication. |
| void OH_HiTrace_StartTrace(const char *name) | - | Marks the start of a synchronous trace. The synchronous tracing APIs OH_HiTrace_StartTrace and OH_HiTrace_FinishTrace must be used in pairs. The OH_HiTrace_StartTrace and OH_HiTrace_FinishTrace function pairs can be nested. During tracing and parsing, the stack data structure is used for matching. 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 function must be used together with OH_HiTrace_StartTrace. During trace parsing, this function matches the latest OH_HiTrace_StartTrace in the implementation process. Since API version 19, you are advised to use OH_HiTrace_FinishTraceEx to control trace output by 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 OH_HiTrace_StartAsyncTraceEx to control trace output and clustering by level. |
| 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. The name and taskId must be the same as those of the OH_HiTrace_StartAsyncTrace API. Since API version 19, you are advised to use OH_HiTrace_FinishAsyncTraceEx to control trace output by 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 OH_HiTrace_CountTraceEx to control the trace output by 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. The synchronous tracing APIs OH_HiTrace_StartTraceEx and OH_HiTrace_FinishTraceEx must be used in pairs. The OH_HiTrace_StartTraceEx and OH_HiTrace_FinishTraceEx function pairs can be nested. During tracing and parsing, the stack data structure is used for matching. |
| 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 in pair with OH_HiTrace_StartTraceEx. The level parameter must be the same as that of OH_HiTrace_StartTraceEx. During trace data parsing, this function matches the latest OH_HiTrace_StartTraceEx in the implementation 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. The level, name, and taskId parameters must be the same as those of the OH_HiTrace_StartAsyncTraceEx API. |
| 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 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 |
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 |
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 about the trace point are printed when the OH_HiTrace_Tracepoint API is called. By default, the HiLog logs about the trace point 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 start 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 start 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, which 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 the HITRACE_FLAG_TP_INFO flag is not set, set the HITRACE_FLAG_D2D_TP_INFO flag. In this case, when the information tracing API OH_HiTrace_Tracepoint is called, the HiLog of the tracing point information is printed only when the mode parameter is set to HITRACE_CM_DEVICE. Since: 12 System capability: SystemCapability.HiviewDFX.HiTrace |
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 |
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 |
enum HiTrace_Output_Level
Description
Enumerates the HiTrace output levels. The trace output level lower than the threshold does not take effect. The threshold for the log version is HITRACE_LEVEL_INFO, and that for the no-log version 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 |
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. |
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
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
HiTraceId OH_HiTrace_GetId()
Description
Obtains the HiTraceId in the TLS of the current thread.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Returns
void OH_HiTrace_SetId(const HiTraceId *id)
Description
Sets the given HiTraceId to the TLS of the current thread. If the input parameter is invalid, no operation is performed.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
| Name | Description |
|---|---|
| const HiTraceId *id | HiTraceId to set. |
void OH_HiTrace_ClearId(void)
Description
Sets the HiTraceId in the TLS of the current thread to invalid.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
HiTraceId OH_HiTrace_CreateSpan(void)
Description
Creates a trace span.
Creates a HiTraceId, uses the chainId and spanId in the TLS of the current thread to initialize its chainId and parentSpanId, and generates a new spanId for it.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Returns
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 (client sending) or HITRACE_TP_SR (server receiving), the synchronous HiTraceMeter logging starts. When type is set to HITRACE_TP_CR (client receiving) or HITRACE_TP_SS (server sending), the synchronous HiTraceMeter logging ends. When type is set to HITRACE_TP_GENERAL, HiTraceMeter logging is not performed.
The trace points must be used in pairs: HITRACE_TP_CS with HITRACE_TP_CR, and HITRACE_TP_SR with HITRACE_TP_SS. 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. |
void OH_HiTrace_InitId(HiTraceId *id)
Description
Initializes a HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
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
bool OH_HiTrace_IsIdValid(const HiTraceId *id)
Description
Checks whether a 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. |
bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag)
Description
Checks whether a trace flag is enabled for a 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. |
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. |
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. |
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. |
uint64_t OH_HiTrace_GetChainId(const HiTraceId *id)
Description
Obtains the trace chain ID from 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. |
void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId)
Description
Sets the trace chain ID to HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id)
Description
Obtains the span ID from the current 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. |
void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId)
Description
Sets the span ID to HiTraceId.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id)
Description
Obtains the parent span ID from the current 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. |
void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId)
Description
Sets the parentSpanId field in the HiTraceId struct.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 12
Parameters
int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len)
Description
Converts a HiTraceId to a byte array for caching 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. |
void OH_HiTrace_StartTrace(const char *name)
Description
Marks the start of a synchronous trace.
The synchronous tracing APIs OH_HiTrace_StartTrace and OH_HiTrace_FinishTrace must be used in pairs.
The OH_HiTrace_StartTrace and OH_HiTrace_FinishTrace function pairs can be nested. During tracing and parsing, the stack data structure is used for matching.
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. |
void OH_HiTrace_FinishTrace(void)
Description
Marks the end of a synchronous trace.
This function must be used together with OH_HiTrace_StartTrace. During trace parsing, this function matches the latest OH_HiTrace_StartTrace in the implementation process.
Since API version 19, you are advised to use OH_HiTrace_FinishTraceEx to control trace output by level.
System capability: SystemCapability.HiviewDFX.HiTrace
Since: 10
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 OH_HiTrace_StartAsyncTraceEx to control trace output and clustering by 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. |
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. The name and taskId must be the same as those of the OH_HiTrace_StartAsyncTrace API.
Since API version 19, you are advised to use OH_HiTrace_FinishAsyncTraceEx to control trace output by 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. |
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 OH_HiTrace_CountTraceEx to control the trace output by 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. |
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.
The synchronous tracing APIs OH_HiTrace_StartTraceEx and OH_HiTrace_FinishTraceEx must be used in pairs.
The OH_HiTrace_StartTraceEx and OH_HiTrace_FinishTraceEx function pairs can be nested. During tracing and parsing, the stack data structure is used for matching.
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". |
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 in pair with OH_HiTrace_StartTraceEx. The level parameter must be the same as that of OH_HiTrace_StartTraceEx.
During trace data parsing, this function matches the latest OH_HiTrace_StartTraceEx in the implementation process.
Since: 19
Parameters
| Name | Description |
|---|---|
| HiTrace_Output_Level level | Trace output level. |
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". |
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. The level, name, and taskId parameters must be the same as those of the OH_HiTrace_StartAsyncTraceEx API.
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. |
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. |
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. |
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 an asynchronous 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 OH_HiTrace_TraceEventListener type. |
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. |