跟踪：C 和 C++ 宏

将组件设置为跟踪提供程序后，您可以使用这些 C 和 C++ 宏记录跟踪数据。如需了解详情，请参阅在代码中添加跟踪记录。

这些宏在 //zircon/system/ulib/trace/include/lib/trace/internal/event_common.h 中定义。

对宏进行编码

如需记录包含跟踪宏的 value，请务必对每个值进行正确编码。请根据要记录的数据类型使用相应的宏。

C++ 说明

在 C++ 中，当您使用字面量常量时，类型推断需要提示才能正确获取大小、符号和类型。

例如，值 77 是否为有符号的 32 位整数？无符号 32 位整数？甚至是某种 64 位整数？

跟踪宏中的类型推断根据标准 C++ 规则工作：

• 77 是一个有符号的 32 位整数 TA_INT32
• 77U 是一个无符号的 32 位整数 TA_UINT32
• 77L 是一个有符号的 64 位整数 TA_INT64
• 77LU 是一个无符号的 64 位整数 TA_UINT64

这也意味着，如果浮点数为整数值，则需要明确注明浮点值。

例如：

• 77的会员级别为TA_INT32。
• 77.的会员级别为TA_DOUBLE。

如果您使用常量，如果您要直接表示值，则应考虑保留编码宏，或者使用相应的 const 类型。以下示例均执行相同的操作，但展示的是明确定义的类型、类型宏的用法，以及不建议使用的示例。

const int32_t my_id = 77;                       // well defined type
TRACE_INSTANT("category", "name", "int", my_id);

#define MY_ID   (TA_INT32(77))                  // uses the typing macro
TRACE_INSTANT("category", "name", "int", MY_ID);

TRACE_INSTANT("category", "name", "int", 77);   // discouraged

跟踪已启用

 Returns true if tracing is enabled.

 Usage:

     if (TRACE_ENABLED()) {
         // do something possibly expensive only when tracing is enabled
     }

已启用跟踪类别

 Returns true if tracing of the specified category has been enabled (which
 implies that |TRACE_ENABLED()| is also true).

 |category_literal| must be a null-terminated static string constant.

 Usage:

     if (TRACE_CATEGORY_ENABLED("category")) {
         // do something possibly expensive only when tracing this category
     }

跟踪

 Returns a new unique 64-bit unsigned integer (within this process).
 Each invocation returns a different non-zero value.
 Useful for generating identifiers for async and flow events.

 Usage:

     trace_async_id_t async_id = TRACE_NONCE();
     TRACE_ASYNC_BEGIN("category", "name", async_id);
     // a little while later...
     TRACE_ASYNC_END("category", "name", async_id);

即时跟踪

 Writes an instant event representing a single moment in time (a probe).

 0 to 15 arguments can be associated with the event, each of which is used
 to annotate the moment with additional information.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |scope| is |TRACE_SCOPE_THREAD|, |TRACE_SCOPE_PROCESS|, or |TRACE_SCOPE_GLOBAL|.
 |args| is the list of argument key/value pairs.

 Usage:

     TRACE_INSTANT("category", "name", TRACE_SCOPE_PROCESS, "x", TA_INT32(42));

跟踪计数器

 Writes a counter event with the specified id.

 The arguments to this event are numeric samples are typically represented by
 the visualizer as a stacked area chart.  The id serves to distinguish multiple
 instances of counters that share the same category and name within the
 same process.

 1 to 15 numeric arguments can be associated with the event, each of which is
 interpreted as a distinct time series.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |counter_id| is the correlation id of the counter.
              Must be unique for a given process, category, and name combination.
 |args| is the list of argument key/value pairs.

 Usage:

     trace_counter_id_t counter_id = 555;
     TRACE_COUNTER("category", "name", counter_id, "x", TA_INT32(42), "y", TA_DOUBLE(2.0))

TRACE_DURATION

 Writes a duration event that ends when the current scope exits.

 Durations describe work that is happening synchronously on one thread.
 They can be nested to represent a control flow stack.

 0 to 15 arguments can be associated with the event, each of which is used
 to annotate the duration with additional information.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |args| is the list of argument key/value pairs.

 Usage:

     void function(int arg) {
         TRACE_DURATION("category", "name", "arg", TA_INT32(arg));
         // do something useful here
     }

TRACE_DURATION_BEGIN

 Writes a duration begin event only.
 This event must be matched by a duration end event with the same category and name.

 Durations describe work that is happening synchronously on one thread.
 They can be nested to represent a control flow stack.

 0 to 15 arguments can be associated with the event, each of which is used
 to annotate the duration with additional information.  The arguments provided
 to matching duration begin and duration end events are combined together in
 the trace; it is not necessary to repeat them.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |args| is the list of argument key/value pairs.

 Usage:

     TRACE_DURATION_BEGIN("category", "name", "x", TA_INT32(42));

TRACE_DURATION_END

 Writes a duration end event only.

 Durations describe work that is happening synchronously on one thread.
 They can be nested to represent a control flow stack.

 0 to 15 arguments can be associated with the event, each of which is used
 to annotate the duration with additional information.  The arguments provided
 to matching duration begin and duration end events are combined together in
 the trace; it is not necessary to repeat them.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |args| is the list of argument key/value pairs.

 Usage:

     TRACE_DURATION_END("category", "name", "x", TA_INT32(42));

跟踪_ASYNC_BEGIN

 Writes an asynchronous begin event with the specified id.
 This event may be followed by async instant events and must be matched by
 an async end event with the same category, name, and id.

 Asynchronous events describe work that is happening asynchronously and that
 may span multiple threads.  Asynchronous events do not nest.  The id serves
 to correlate the progress of distinct asynchronous operations that share
 the same category and name within the same process.

 0 to 15 arguments can be associated with the event, each of which is used
 to annotate the asynchronous operation with additional information.  The
 arguments provided to matching async begin, async instant, and async end
 events are combined together in the trace; it is not necessary to repeat them.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |async_id| is the correlation id of the asynchronous operation.
            Must be unique for a given process, category, and name combination.
 |args| is the list of argument key/value pairs.

 Usage:

     trace_async_id_t async_id = 555;
     TRACE_ASYNC_BEGIN("category", "name", async_id, "x", TA_INT32(42));

即时跟踪

 Writes an asynchronous instant event with the specified id.

 Asynchronous events describe work that is happening asynchronously and that
 may span multiple threads.  Asynchronous events do not nest.  The id serves
 to correlate the progress of distinct asynchronous operations that share
 the same category and name within the same process.

 0 to 15 arguments can be associated with the event, each of which is used
 to annotate the asynchronous operation with additional information.  The
 arguments provided to matching async begin, async instant, and async end
 events are combined together in the trace; it is not necessary to repeat them.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |async_id| is the correlation id of the asynchronous operation.
            Must be unique for a given process, category, and name combination.
 |args| is the list of argument key/value pairs.

 Usage:

     trace_async_id_t async_id = 555;
     TRACE_ASYNC_INSTANT("category", "name", async_id, "x", TA_INT32(42));

跟踪_ASYNC_END

 Writes an asynchronous end event with the specified id.

 Asynchronous events describe work that is happening asynchronously and that
 may span multiple threads.  Asynchronous events do not nest.  The id serves
 to correlate the progress of distinct asynchronous operations that share
 the same category and name within the same process.

 0 to 15 arguments can be associated with the event, each of which is used
 to annotate the asynchronous operation with additional information.  The
 arguments provided to matching async begin, async instant, and async end
 events are combined together in the trace; it is not necessary to repeat them.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |async_id| is the correlation id of the asynchronous operation.
            Must be unique for a given process, category, and name combination.
 |args| is the list of argument key/value pairs.

 Usage:

     trace_async_id_t async_id = 555;
     TRACE_ASYNC_END("category", "name", async_id, "x", TA_INT32(42));

TRACE_FLOW_BEGIN

 Writes a flow begin event with the specified id.
 This event may be followed by flow steps events and must be matched by
 a flow end event with the same category, name, and id.

 Flow events describe control flow handoffs between threads or across processes.
 They are typically represented as arrows in a visualizer.  Flow arrows are
 from the end of the duration event that encloses the beginning of the flow
 to the beginning of the duration event that encloses the next step or the
 end of the flow.  The id serves to correlate flows that share the same
 category and name across processes.

 This event must be enclosed in a duration event that represents where
 the flow handoff occurs.

 0 to 15 arguments can be associated with the event, each of which is used
 to annotate the flow with additional information.  The arguments provided
 to matching flow begin, flow step, and flow end events are combined together
 in the trace; it is not necessary to repeat them.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |flow_id| is the correlation id of the flow.
           Must be unique for a given category and name combination.
 |args| is the list of argument key/value pairs.

 Usage:

     trace_flow_id_t flow_id = 555;
     TRACE_FLOW_BEGIN("category", "name", flow_id, "x", TA_INT32(42));

TRACE_FLOW_STEP

 Writes a flow step event with the specified id.

 Flow events describe control flow handoffs between threads or across processes.
 They are typically represented as arrows in a visualizer.  Flow arrows are
 from the end of the duration event that encloses the beginning of the flow
 to the beginning of the duration event that encloses the next step or the
 end of the flow.  The id serves to correlate flows that share the same
 category and name across processes.

 This event must be enclosed in a duration event that represents where
 the flow handoff occurs.

 0 to 15 arguments can be associated with the event, each of which is used
 to annotate the flow with additional information.  The arguments provided
 to matching flow begin, flow step, and flow end events are combined together
 in the trace; it is not necessary to repeat them.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |flow_id| is the correlation id of the flow.
           Must be unique for a given category and name combination.
 |args| is the list of argument key/value pairs.

 Usage:

     trace_flow_id_t flow_id = 555;
     TRACE_FLOW_STEP("category", "name", flow_id, "x", TA_INT32(42));

TRACE_FLOW_END

 Writes a flow end event with the specified id.

 Flow events describe control flow handoffs between threads or across processes.
 They are typically represented as arrows in a visualizer.  Flow arrows are
 from the end of the duration event that encloses the beginning of the flow
 to the beginning of the duration event that encloses the next step or the
 end of the flow.  The id serves to correlate flows that share the same
 category and name across processes.

 This event must be enclosed in a duration event that represents where
 the flow handoff occurs.

 0 to 15 arguments can be associated with the event, each of which is used
 to annotate the flow with additional information.  The arguments provided
 to matching flow begin, flow step, and flow end events are combined together
 in the trace; it is not necessary to repeat them.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |flow_id| is the correlation id of the flow.
           Must be unique for a given category and name combination.
 |args| is the list of argument key/value pairs.

 Usage:

     trace_flow_id_t id = 555;
     TRACE_FLOW_END("category", "name", flow_id, "x", TA_INT32(42));

跟踪_BLOB_事件

 Writes a large blob record with the given blob data and metadata.
 Here metadata includes timestamp, thread and process information, and arguments,
 which is what most event records contain.

 Blobs that exceed |TRACE_ENCODED_RECORD_MAX_TOTAL_LENGTH| will be silently
 ignored, as will blobs that cannot fit within the remaining space in the
 trace buffer.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |blob| is a pointer to the data.
 |blob_size| is the size, in bytes, of the data.

跟踪_BLOB_ATTACHMENT

 Writes a large blob record with the given blob data, with only a
 category and name associated with the blob. This will not contain much
 additional metadata. This means timestamp, thread and process information,
 and arguments are not included with the record.

 Blobs that exceed |TRACE_ENCODED_RECORD_MAX_TOTAL_LENGTH| will be silently
 ignored, as will blobs that cannot fit within the remaining space in the
 trace buffer.

 |category_literal| and |name_literal| must be null-terminated static string constants.
 |blob| is a pointer to the data.
 |blob_size| is the size, in bytes, of the data.

TRACE_KERNEL_OBJECT

 Writes a description of a kernel object indicated by |handle|,
 including its koid, name, and the supplied arguments.

 0 to 15 arguments can be associated with the record, each of which is used
 to annotate the handle with additional information.

 |handle| is the handle of the object being described.
 |args| is the list of argument key/value pairs.

 Usage:

     zx_handle_t handle = ...;
     TRACE_KERNEL_OBJECT(handle, "description", TA_STRING("some object"));