將元件設為追蹤提供者後,您就可以使用這些 C 和 C++ 巨集記錄追蹤資料。詳情請參閱「在程式碼中加入追蹤記錄」。
這些巨集在 //zircon/system/ulib/trace/include/lib/trace/internal/event_common.h
中定義。
編碼巨集
想要使用追蹤巨集錄製 value
時,請務必正確為每個值進行編碼。請根據您要記錄的資料類型使用相應的巨集。
微距 | 說明 |
---|---|
TA_NULL |
C++ 的選用功能
這個巨集不接受任何引數。就可以做為 在 C++ 中,您也可以使用 |
TA_BOOL |
C++ 的選用功能 布林值。 |
TA_INT32 |
C++ 的選用功能 帶正負號的 32 位元整數值。 |
TA_UINT32 |
C++ 的選用功能 未簽署的 32 位元整數值。 |
TA_INT64 |
C++ 的選用功能 帶正負號的 64 位元整數值。 |
TA_UINT64 |
C++ 的選用功能 未簽署的 32 位元整數值。 |
TA_DOUBLE |
C++ 的選用功能 雙精度浮點值。 |
TA_CHAR_ARRAY |
C++ 必填 長度的字元陣列,系統會複製內容,而非快取。 這個巨集接受兩個引數。第一個引數是字元陣列的指標。第二個引數是陣列的長度。 |
TA_STRING |
C++ 的選用功能 由 NULL 終止的動態字串,系統會複製而非快取。 |
TA_STRING_LITERAL |
C++ 必填 空值已終止的動態字串,並快取。 |
TA_POINTER |
C++ 的選用功能 記錄記憶體位址,而非目標的指標值。 |
TA_KOID |
C++ 必填 核心物件 ID。詳情請參閱「Zircon 核心物件 」。 |
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
}
TRACE_CATEGORY_已啟用
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
}
TRACE_NONCE
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));
TRACE_COUNTER
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));
TRACE_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));
TRACE_ASYNC_INSTANT
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));
TRACE_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));
追蹤黑色事件
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.
追蹤
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.
跟蹤
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"));