本文件說明如何在 Fuchsia 系統中，為驅動程式庫新增追蹤記錄。
總覽
如需追蹤功能的總覽，請參閱「Fuchsia 追蹤系統」一文。不過，驅動程式不需要指定追蹤程式。驅動程式代管程序會為其提供驅動程式。
如需追蹤功能的教學課程，請參閱「在程式碼中加入追蹤功能」。如需追蹤 API 參考資料，請參閱「追蹤：C 和 C++ 巨集」一文。
新增追蹤記錄
如要新增追蹤驅動程式庫，您必須更新驅動程式庫的原始碼和 BUILD.gn 檔案。
原始碼更新
如要在驅動程式庫元件中新增追蹤記錄，請更新原始碼，從 lib/trace/event.h 叫用 TRACE_*() 巨集，例如：
#include <lib/trace/event.h>
void DoSomething(int a, std::string b) {
TRACE_DURATION("example", "DoSomething", "a", a, "b", b);
// Do something
}
大多數巨集的前兩個引數是追蹤類別和事件名稱。在本例中，這兩個元素分別為 example 和 DoSomething。
追蹤類別可讓您指定追蹤系統收集的資料類型。如果未要求類別，系統就不會收集任何資料。驅動程式庫中的類別可以重複。一個通常會將多個事件分組到相同類別底下。
追蹤記錄會包含事件名稱，以便說明事件。每個事件通常都有這個值。
BUILD.gn 更新
如要採用追蹤支援，請將下列目標新增至驅動程式的 BUILD.gn：
fuchsia_driver("my_driver") {
deps = [
...
"//zircon/system/ulib/trace",
]
}
使用追蹤記錄進行建構
如要追蹤啟動時載入的驅動程式，請使用額外的 --with-base=//bundles/packages/prod:tracing 選項設定 Fuchsia 建構設定，例如：
$ fx set workstation_eng.x64 --with-base=//bundles/packages/prod:tracing
$ fx build
如果不使用這個選項，驅動程式庫啟動時就不會顯示 TraceManager。因此，當 TraceManager 稍後啟動時，驅動程式庫無法參與追蹤。
如要進一步瞭解 fx set，請參閱「fx 工作流程」(或執行 fx help set)。
具追蹤功能的靴子
Fuchsia 使用核心指令列旗標，在啟動期間啟用驅動程式的追蹤功能：
driver.tracing.enable=1
這是 Fuchsia 裝置的預設設定。
如要停止參與 Fuchsia 追蹤中的驅動程式，請使用下列指令列標記啟動核心：
driver.tracing.enable=0
有關啟動特定 Fuchsia 裝置的操作說明，請參閱硬體或 QEMU 的說明文件。啟動期間追蹤不需要任何特殊動作。
使用追蹤記錄
使用 ffx trace 錄製追蹤記錄，並透過 Perfetto 檢視器查看結果。
以下範例指令使用上方「原始碼更新」一節中所述的 example 類別：
$ ffx trace start --categories "example,kernel:sched,kernel:meta"
如果您要以視覺化方式呈現結果，則必須有 kernel:sched,kernel:meta 類別。視覺化工具想要將追蹤記錄資料與執行緒和程序建立關聯，而且需要核心透過這些類別提供的資料。
如需更多詳細資料，以及在不含 ffx 的 Fuuchsia 裝置上直接追蹤操作說明，請參閱「錄製追蹤記錄以進行效能分析」。
其他資訊
詳情請參閱 Fuchsia 追蹤指南。