本頁說明如何在 Fuchsia 元件的程式碼中加入追蹤記錄。
必要條件
開始之前，請確認您已完成下列工作：
在程式碼中使用追蹤巨集
將元件註冊為追蹤程式後，您就可以在元件的程式碼中加入追蹤記錄。
以下是通常相當實用的動作，您可以使用追蹤巨集輕鬆加入程式碼：
- 追蹤即時事件。
- 停用追蹤功能。
- 判斷追蹤功能是否開啟。
- 設定事件時間。
如需所有可用追蹤巨集的清單，請參閱「追蹤：C 和 C++ 巨集」。
追蹤即時事件
下列範例 (適用於 C 和 C++) 會寫入代表單一時刻的即時事件：
TRACE_INSTANT("helloworld", "hello_world_test", TRACE_SCOPE_PROCESS, "message", TA_STRING("Hello, World!"));
這個範例指定了 helloworld 類別、hello_world_test 名稱、TRACE_SCOPE_PROCESS 的範圍，以及鍵/值組合。
如要進一步瞭解 TRACE_INSTANT 巨集，請參閱 TRACE_INSTANT。
停用追蹤功能
在某些情況下，您可能想完全停用追蹤功能 (例如，即將發布元件時)。如果您在程式碼中加入 NTRACE 巨集，追蹤巨集將不會產生任何程式碼。
以下範例 (適用於 C 和 C++) 顯示 NTRACE 巨集：
#define NTRACE // disable tracing
#include <lib/trace/event.h>
請務必在 #include 陳述式之前定義 NTRACE 巨集。
在以下範例中，rx_count 和 tx_count 欄位僅適用於追蹤，因此如果 NTRACE 宣告了追蹤功能已停用，表示欄位不會佔用 my_statistics_t 結構的空間。
typedef struct {
#ifndef NTRACE // reads as "if tracing is not disabled"
uint64_t rx_count;
uint64_t tx_count;
#endif
uint64_t npackets;
} my_statistics_t;
不過，如果您需要編譯程式碼以管理統計資料記錄，可以使用 TRACE_INSTANT 巨集：
#ifndef NTRACE
status.tx_count++;
TRACE_INSTANT("bandwidth", "txpackets", TRACE_SCOPE_PROCESS,
"count", TA_UINT64(status.tx_count));
#endif // NTRACE
如要進一步瞭解 NTRACE 巨集，請參閱 NTRACE。
判斷是否已啟用追蹤功能
在某些情況下，您可能需要判斷是否在執行階段開啟追蹤功能。如果因為 NTRACE 未定義，而在程式碼中編譯追蹤，TRACE_ENABLED() 巨集會判斷追蹤提供者的追蹤功能是否開啟。如果追蹤記錄已編譯，TRACE_ENABLED() 一律會傳回 false。
#ifndef NTRACE
if (TRACE_ENABLED()) {
int v = do_something_expensive();
TRACE_INSTANT(...
}
#endif // NTRACE
上述範例 (適用於 C 和 C++) 同時使用 #ifndef 和 TRACE_ENABLED() 巨集，因為在已停用追蹤功能的程式碼版本中，函式 do_something_expensive() 可能不存在。
如要進一步瞭解 TRACE_ENABLED 巨集，請參閱 TRACE_ENABLED。
設定活動時間
如果您需要為特定函式或程序計時，請參閱 blobfs vnode 建構函式中的下方範例 (適用於 C++)：
zx_status_t VnodeBlob::InitCompressed() {
TRACE_DURATION("blobfs", "Blobfs::InitCompressed", "size", inode_.blob_size,
"blocks", inode_.num_blocks);
...
這個範例會記錄建構函式所花費的時間長度，以及區塊的大小和區塊數量。由於這是 C++ 範例，編譯器能夠推論資料類型。
如要進一步瞭解 TRACE_DURATION 巨集，請參閱 TRACE_DURATION。
將追蹤程式碼加入元件後，您現在可以從元件收集追蹤記錄。詳情請參閱下一節「錄製追蹤記錄並以視覺化方式呈現」頁面。