From 47a84d878b37a3a8838115a4f8fbc9704ee3d494 Mon Sep 17 00:00:00 2001 From: lixing0101 Date: Wed, 24 Apr 2024 16:29:25 +0800 Subject: [PATCH] add hitracechain interface Signed-off-by: lixing0101 --- hiviewdfx/hitrace/include/hitrace/trace.h | 592 +++++++++++++++++++++- hiviewdfx/hitrace/libhitrace.ndk.json | 63 +++ 2 files changed, 629 insertions(+), 26 deletions(-) diff --git a/hiviewdfx/hitrace/include/hitrace/trace.h b/hiviewdfx/hitrace/include/hitrace/trace.h index 1940d14b1..a1328cb6e 100644 --- a/hiviewdfx/hitrace/include/hitrace/trace.h +++ b/hiviewdfx/hitrace/include/hitrace/trace.h @@ -24,43 +24,583 @@ * You can call the APIs provided by hiTraceMeter in your own service logic to effectively * track service processes and check the system performance. * + * @brief hitraceChain provides APIs for cross-thread and cross-process distributed tracing. + * hiTraceChain generates a unique chain ID for a service process and passes it to various information (including + * application events, system events, and logs) specific to the service process. + * During debugging and fault locating, you can use the unique chain ID to quickly correlate various information related + * to the service process. + * * @syscap SystemCapability.HiviewDFX.HiTrace * * @since 10 */ -/** - * @file trace.h - * - * @brief Defines APIs of the HiTraceMeter module for performance trace. - * - * Sample code: \n - * Synchronous timeslice trace event: \n - * OH_HiTrace_StartTrace("hitraceTest");\n - * OH_HiTrace_FinishTrace();\n - * Output: \n - * <...>-1668 (-------) [003] .... 135.059377: tracing_mark_write: B|1668|H:hitraceTest \n - * <...>-1668 (-------) [003] .... 135.059415: tracing_mark_write: E|1668| \n - * Asynchronous timeslice trace event:\n - * OH_HiTrace_StartAsyncTrace("hitraceTest", 123); \n - * OH_HiTrace_FinishAsyncTrace("hitraceTest", 123); \n - * Output: \n - * <...>-2477 (-------) [001] .... 396.427165: tracing_mark_write: S|2477|H:hitraceTest 123 \n - * <...>-2477 (-------) [001] .... 396.427196: tracing_mark_write: F|2477|H:hitraceTest 123 \n - * Integer value trace event:\n - * OH_HiTrace_CountTrace("hitraceTest", 500); \n - * Output: \n - * <...>-2638 (-------) [002] .... 458.904382: tracing_mark_write: C|2638|H:hitraceTest 500 \n - * - * @syscap SystemCapability.HiviewDFX.HiTrace - * @since 10 - */ + /** + * @file trace.h + * + * @brief Defines APIs of the HiTraceMeter module for performance trace. + * + * Sample code: \n + * Synchronous timeslice trace event: \n + * OH_HiTrace_StartTrace("hitraceTest");\n + * OH_HiTrace_FinishTrace();\n + * Output: \n + * <...>-1668 (-------) [003] .... 135.059377: tracing_mark_write: B|1668|H:hitraceTest \n + * <...>-1668 (-------) [003] .... 135.059415: tracing_mark_write: E|1668| \n + * Asynchronous timeslice trace event:\n + * OH_HiTrace_StartAsyncTrace("hitraceTest", 123); \n + * OH_HiTrace_FinishAsyncTrace("hitraceTest", 123); \n + * Output: \n + * <...>-2477 (-------) [001] .... 396.427165: tracing_mark_write: S|2477|H:hitraceTest 123 \n + * <...>-2477 (-------) [001] .... 396.427196: tracing_mark_write: F|2477|H:hitraceTest 123 \n + * Integer value trace event:\n + * OH_HiTrace_CountTrace("hitraceTest", 500); \n + * Output: \n + * <...>-2638 (-------) [002] .... 458.904382: tracing_mark_write: C|2638|H:hitraceTest 500 \n + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * @since 10 + */ #include #ifdef __cplusplus extern "C" { #endif +/** + * @brief Defines whether a HiTraceId instance is valid. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +typedef enum HiTraceId_Valid { + /** + * @brief Invalid HiTraceId instance. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_ID_INVALID = 0, + + /** + * @brief Valid HiTraceId instance. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_ID_VALID = 1, +} HiTraceId_Valid; + +/** + * @brief Enumerates the HiTrace version numbers. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +typedef enum HiTrace_Version { + /** + * @brief Version 1. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_VER_1 = 0, +} HiTrace_Version; + +/** + * @brief Enumerates the HiTrace flags. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +typedef enum HiTrace_Flag { + /** + * @brief Default flag. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_FLAG_DEFAULT = 0, + + /** + * @brief Both synchronous and asynchronous calls are traced. By default, only synchronous calls are traced. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_FLAG_INCLUDE_ASYNC = 1 << 0, + + /** + * @brief No spans are created. By default, spans are created. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_FLAG_DONOT_CREATE_SPAN = 1 << 1, + + /** + * @brief Trace points are automatically added to spans. By default, no trace point is added. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_FLAG_TP_INFO = 1 << 2, + + /** + * @brief 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. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_FLAG_NO_BE_INFO = 1 << 3, + + /** + * @brief The ID is not added to the log. By default, the ID is added to the log. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_FLAG_DONOT_ENABLE_LOG = 1 << 4, + + /** + * @brief Tracing is triggered by faults. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_FLAG_FAULT_TRIGGER = 1 << 5, + + /** + * @brief Trace points are added only for call chain trace between devices. + * By default, device-to-device trace points are not added. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_FLAG_D2D_TP_INFO = 1 << 6, +} HiTrace_Flag; + +/** + * @brief Enumerates the HiTrace trace point types. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +typedef enum HiTrace_Tracepoint_Type { + /** + * @brief CS trace point. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_TP_CS = 0, + /** + * @brief CR trace point. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_TP_CR = 1, + /** + * @brief SS trace point. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_TP_SS = 2, + /** + * @brief SR trace point. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_TP_SR = 3, + /** + * @brief General trace point. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_TP_GENERAL = 4, +} HiTrace_Tracepoint_Type; + +/** + * @brief Enumerates the HiTrace communication modes. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +typedef enum HiTrace_Communication_Mode { + /** + * @brief Default communication mode. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_CM_DEFAULT = 0, + /** + * @brief Inter-thread communication. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_CM_THREAD = 1, + /** + * @brief Inter-process communication. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_CM_PROCESS = 2, + /** + * @brief Inter-device communication. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ + HITRACE_CM_DEVICE = 3, +} HiTrace_Communication_Mode; + +/** + * @brief Defines a HiTraceId instance. + * + * @struct HiTraceId + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +typedef struct HiTraceId { +#if __BYTE_ORDER == __LITTLE_ENDIAN + /** Whether the HiTraceId instance is valid. */ + uint64_t valid : 1; + /** Version number of the HiTraceId instance. */ + uint64_t ver : 3; + /** Chain ID of the HiTraceId instance. */ + uint64_t chainId : 60; + /** Flag of the HiTraceId instance. */ + uint64_t flags : 12; + /** Span ID of the HiTraceId instance. */ + uint64_t spanId : 26; + /** Parent span ID of the HiTraceId instance. */ + uint64_t parentSpanId : 26; +#elif __BYTE_ORDER == __BIG_ENDIAN + /** Chain ID of the HiTraceId instance. */ + uint64_t chainId : 60; + /** Version number of the HiTraceId instance. */ + uint64_t ver : 3; + /** Whether the HiTraceId instance is valid. */ + uint64_t valid : 1; + /** Parent span ID of the HiTraceId instance. */ + uint64_t parentSpanId : 26; + /** Span ID of the HiTraceId instance. */ + uint64_t spanId : 26; + /** Flag of the HiTraceId instance. */ + uint64_t flags : 12; +#else +#error "ERROR: No BIG_LITTLE_ENDIAN defines." +#endif +} HiTraceId; + +/** + * @brief Starts tracing of 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. + * + * @param name Pointer to a process name. + * @param flags Trace flag. + * @return Returns the created HiTraceId instance. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +HiTraceId OH_HiTrace_BeginChain(const char *name, int flags); + +/** + * @brief Ends tracing and clears the HiTraceId instance of the calling thread from the TLS. + * + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_EndChain(); + +/** + * @brief Obtains the trace ID of the calling thread from the TLS. + * + * + * @return Returns the trace ID of the calling thread. If the calling thread does not have a trace ID, + * an invalid trace ID is returned. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +HiTraceId OH_HiTrace_GetId(); + +/** + * @brief 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. + * + * @param id Trace ID to set. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_SetId(const HiTraceId *id); + +/** + * @brief Clears the trace ID of the calling thread and invalidates it. + * + * This API clears the HiTraceId instance in the TLS of the calling thread. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_ClearId(void); + +/** + * @brief 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. + * + * @return Returns a valid span ID. If span creation is not allowed, the ID of the calling thread is traced. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +HiTraceId OH_HiTrace_CreateSpan(void); + +/** + * @brief Prints HiTrace information, including the trace ID. + * + * This API prints trace point information, including the communication mode, trace point type, timestamp, and span. + * + * @param mode Communication mode for the trace point. + * @param type Trace point type. + * @param id Trace ID. + * @param fmt Custom information to print. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_Tracepoint( + HiTrace_Communication_Mode mode, HiTrace_Tracepoint_Type type, const HiTraceId *id, const char *fmt, ...); + +/** + * @brief Initializes a HiTraceId structure. + * + * @param id ID of the HiTraceId structure to be initialized. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_InitId(HiTraceId *id); + +/** + * @brief Creates a HiTraceId structure based on a byte array. + * + * @param id ID of the HiTraceId structure to be created. + * @param pIdArray Byte array. + * @param len Length of the byte array. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_IdFromBytes(HiTraceId *id, const uint8_t *pIdArray, int len); + +/** + * @brief Checks whether a HiTraceId instance is valid. + * + * + * @param id HiTraceId instance to check. + * @return Returns true if the HiTraceId instance is valid; returns false otherwise. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +bool OH_HiTrace_IsIdValid(const HiTraceId *id); + +/** + * @brief Checks whether the specified trace flag in a HiTraceId instance is enabled. + * + * + * @param id HiTraceId instance to check. + * @param flag Specified trace flag. + * @return Returns true if the specified trace flag is enabled; returns false otherwise. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +bool OH_HiTrace_IsFlagEnabled(const HiTraceId *id, HiTrace_Flag flag); + +/** + * @brief Enables the specified trace flag in a HiTraceId instance. + * + * + * @param id HiTraceId instance for which you want to enable the specified trace flag. + * @param flag Specified trace flag. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_EnableFlag(const HiTraceId *id, HiTrace_Flag flag); + +/** + * @brief Obtains the trace flag set in a HiTraceId instance. + * + * @param id HiTraceId instance. + * + * @return Returns the trace flag set in the specified HiTraceId instance. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +int OH_HiTrace_GetFlags(const HiTraceId *id); + +/** + * @brief Sets the trace flag for a HiTraceId instance. + * + * @param id HiTraceId instance. + * @param flags Trace flag to set. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_SetFlags(HiTraceId *id, int flags); + +/** + * @brief Obtains the trace chain ID. + * + * @param id HiTraceId instance for which you want to obtain the trace chain ID. + * + * @return Returns the trace chain ID of the specified HiTraceId instance. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +uint64_t OH_HiTrace_GetChainId(const HiTraceId *id); + +/** + * @brief Sets the trace chain ID to a HiTraceId instance + * + * @param id HiTraceId instance. + * @param chainId Trace chain ID to set. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_SetChainId(HiTraceId *id, uint64_t chainId); + +/** + * @brief Obtains the span ID in a HiTraceId instance. + * + * @param id HiTraceId instance for which you want to obtain the span ID. + * + * @return Returns the span ID in the specified HiTraceId instance. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +uint64_t OH_HiTrace_GetSpanId(const HiTraceId *id); + +/** + * @brief Sets the span ID in a HiTraceId instance. + * + * @param id HiTraceId instance for which you want to set the span ID. + * @param spanId Span ID to set. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_SetSpanId(HiTraceId *id, uint64_t spanId); + +/** + * @brief Obtains the parent span ID in a HiTraceId instance. + * + * @param id HiTraceId instance for which you want to obtain the parent span ID. + * + * @return Returns the parent span ID in the specified HiTraceId instance. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +uint64_t OH_HiTrace_GetParentSpanId(const HiTraceId *id); + +/** + * @brief Sets the parent span ID in a HiTraceId instance. + * + * @param id HiTraceId instance for which you want to set the parent span ID. + * @param parentSpanId Parent span ID to set. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +void OH_HiTrace_SetParentSpanId(HiTraceId *id, uint64_t parentSpanId); + +/** + * @brief Converts a HiTraceId instance into a byte array for caching or communication. + * + * @param id HiTraceId instance to be converted. + * @param pIdArray Byte array. + * @param len Length of the byte array. + * + * @return Returns the length of the byte array after conversion. + * + * @syscap SystemCapability.HiviewDFX.HiTrace + * + * @since 12 + */ +int OH_HiTrace_IdToBytes(const HiTraceId* id, uint8_t* pIdArray, int len); + /** * @brief Marks the start of a synchronous trace task. * diff --git a/hiviewdfx/hitrace/libhitrace.ndk.json b/hiviewdfx/hitrace/libhitrace.ndk.json index accfdcd97..a096a2edd 100644 --- a/hiviewdfx/hitrace/libhitrace.ndk.json +++ b/hiviewdfx/hitrace/libhitrace.ndk.json @@ -13,5 +13,68 @@ }, { "name": "OH_HiTrace_CountTrace" + }, + { + "name": "OH_HiTrace_BeginChain" + }, + { + "name": "OH_HiTrace_EndChain" + }, + { + "name": "OH_HiTrace_GetId" + }, + { + "name": "OH_HiTrace_SetId" + }, + { + "name": "OH_HiTrace_ClearId" + }, + { + "name": "OH_HiTrace_CreateSpan" + }, + { + "name": "OH_HiTrace_Tracepoint" + }, + { + "name": "OH_HiTrace_InitId" + }, + { + "name": "OH_HiTrace_IdFromBytes" + }, + { + "name": "OH_HiTrace_IsIdValid" + }, + { + "name": "OH_HiTrace_IsFlagEnabled" + }, + { + "name": "OH_HiTrace_EnableFlag" + }, + { + "name": "OH_HiTrace_GetFlags" + }, + { + "name": "OH_HiTrace_SetFlags" + }, + { + "name": "OH_HiTrace_GetChainId" + }, + { + "name": "OH_HiTrace_SetChainId" + }, + { + "name": "OH_HiTrace_GetSpanId" + }, + { + "name": "OH_HiTrace_SetSpanId" + }, + { + "name": "OH_HiTrace_GetParentSpanId" + }, + { + "name": "OH_HiTrace_SetParentSpanId" + }, + { + "name": "OH_HiTrace_IdToBytes" } ] \ No newline at end of file