ffx trace 指令可記錄來自 Fuchsia 裝置的診斷追蹤資料。這類資料可用於評估效能問題並進行偵錯、瞭解執行緒、程序和元件之間的互動，以及以視覺化方式呈現整個系統。
概念
Fuchsia 追蹤系統提供一項機制，用於收集、匯總使用者空間程序和 Fuchsia 裝置上的 Zircon 核心的診斷追蹤資訊，並以視覺化方式呈現。追蹤系統由追蹤記錄管理工具、記憶體緩衝區和一或多個追蹤提供者組成。「追蹤提供者」是一種元件，會在裝置上執行追蹤資料的元件，系統可以設有多個追蹤服務供應商。(如要將元件註冊為追蹤提供者，請參閱「註冊追蹤項目」一文)。
ffx trace start 指令會將追蹤記錄的輸出內容儲存為主機上的 .fxt 檔案。您可以在 Perfetto 檢視器中開啟這個檔案，以視覺化方式呈現效能分析的追蹤記錄結果。(如要進一步瞭解 Perfetto，請參閱 Perfetto 說明文件網站)。
根據預設，ffx trace start 指令會嘗試從預先定義的一組追蹤記錄類別收集追蹤記錄資料 (執行 ffx trace start --help 即可查看預設類別)。不過，ffx trace start 也可讓您選取追蹤記錄類別來收集追蹤記錄資料。
一次只能在 Fuchsia 裝置上執行一個追蹤工作階段，而且輸出檔案中只能記錄一項追蹤記錄。在以下範例中，所有輸出檔案都會預設為執行 ffx trace 的目錄中的 trace.fxt，且所有目標裝置都會預設為連線至主機機器的可用 Fuchsia 裝置。
以互動方式執行追蹤記錄
透過互動式追蹤記錄，您可以按下 Enter 鍵，即時決定何時結束追蹤記錄。不過，如果指定 --duration 旗標，追蹤記錄會在達到時間長度時自動停止。(如要進一步瞭解執行追蹤時在緩衝區中儲存結果的方式，請參閱附錄中的緩衝模式選項)。
如要啟動互動式追蹤記錄，請執行下列指令：
ffx trace start
這個指令會輸出類似以下的輸出內容：
$ ffx trace start
Tracing started successfully on "fuchsia-5254-0063-5e7a".
Writing to /Users/alice/trace.fxt
Press <enter> to stop trace.
如要停止追蹤記錄，請按下 Enter 鍵。
該指令會結束，輸出如下所示：
Shutting down recording and writing to file.
Tracing stopped successfully on "fuchsia-5254-0063-5e7a".
Results written to /Users/alice/trace.fxt
Upload to https://ui.perfetto.dev/#!/ to view.
如要分析本次執行作業收集到的結果，請參閱「以視覺化方式呈現追蹤記錄結果」。
在背景執行追蹤記錄
背景追蹤會無限期執行，只要未指定時間長度。如要停止在背景執行的追蹤記錄，您必須執行 ffx trace stop。(如要進一步瞭解追蹤執行時在緩衝區中儲存結果的方式，請參閱附錄中的緩衝模式選項)。
如要啟動背景追蹤記錄，請執行下列指令：
ffx trace start --background
這個指令會輸出類似以下的輸出內容：
$ ffx trace start --background
Tracing started successfully on "fuchsia-5254-0063-5e7a".
Writing to /Users/alice/trace.fxt
Current tracing status:
- fuchsia-5254-0063-5e7a:
- Output file: /Users/alice/trace.fxt
- Duration: indefinite
- Config:
- Categories:
- app,audio,benchmark,blobfs,gfx,input,kernel:meta
如要停止這項追蹤，請參閱「停止追蹤記錄」。
使用計時器在背景執行追蹤記錄
與互動式追蹤記錄類似，您可以在背景執行追蹤，並將其設為在特定時間長度後停止。
如要使用計時器啟動背景追蹤記錄，請執行下列指令：
ffx trace start --background --duration <SECONDS>
將 SECONDS 替換為目標時間長度 (以秒為單位)，例如：
$ ffx trace start --background --duration 20
如要手動停止這項追蹤記錄，請參閱「停止追蹤記錄」。
使用觸發條件在背景執行追蹤記錄
如果追蹤是透過觸發條件執行，則追蹤記錄會在偵測到指定事件時停止。
如要使用觸發條件執行追蹤記錄，請執行下列指令：
ffx trace start --background --trigger <TRIGGER>
將 TRIGGER 替換為使用語法 alert:action 的動作，例如：
$ ffx trace start --background --trigger "myexample:terminate"
如要手動停止這項追蹤記錄，請參閱「停止追蹤記錄」。
查看背景追蹤記錄的狀態
如要查看背景追蹤記錄的狀態，請執行下列指令：
ffx trace status
這個指令會輸出類似以下的輸出內容：
$ ffx trace status
- fuchsia-5254-0063-5e7a:
- Output file: /Users/alice/trace.fxt
- Duration: indefinite
- Config:
- Categories:
- app,audio,benchmark,blobfs,gfx,input,kernel:meta
如果背景沒有追蹤記錄，指令會輸出以下內容：
$ ffx trace status
No active traces running.
停止追蹤記錄
ffx trace stop 指令會停止在背景中執行的追蹤記錄。
如要停止追蹤記錄，請執行下列指令：
ffx trace stop [--output <FILE>]
根據預設，這個指令會停止符合預設目標裝置的追蹤記錄。不過，您也可以使用 –output 標記選取要停止的追蹤記錄，然後停止與輸出檔案相關聯的追蹤記錄。
這個指令會輸出類似以下的輸出內容：
$ ffx trace stop
Tracing stopped successfully on "fuchsia-5254-0063-5e7a".
Results written to /Users/alice/trace.fxt
Upload to https://ui.perfetto.dev/#!/ to view.
如要分析本次執行作業收集到的結果，請參閱「以視覺化方式呈現追蹤記錄結果」。
以視覺化方式呈現追蹤記錄結果
追蹤記錄已完成且建立 .fxt 檔案後，請在 Perfetto 檢視器中開啟檔案，以視覺化方式呈現追蹤記錄結果。
請執行下列步驟：
- 透過網路瀏覽器前往 Perfetto Viewer 網站。
- 按一下導覽列上的「開啟追蹤檔」。
- 從主體機器中選取
trace.fxt檔案。
將 FIDL 追蹤記錄符號化
如果收集的追蹤記錄是透過 kernel:ipc 類別收集，.fxt 追蹤檔會包含幾個在追蹤期間發出的 FIDL 呼叫所對應的頻道訊息事件。這些管道訊息只會包含與 FIDL 呼叫相關聯的序數，而序數為呼叫方法的 SHA-256 雜湊。
Fuchsia 建構目錄包含名稱結尾為 .fidl.json 的檔案。這些檔案包含將序數轉譯為對應 FIDL 方法所需的資訊，並且在 Fuchsia 建構期間產生。只要有 Fuchsia 建構目錄可用，這些檔案就能用來將追蹤檔中的序數，符號化為對應的 FIDL 方法
如要翻譯追蹤檔中的所有序數，請使用下列指令：
ffx trace symbolize --fxt <FXT-FILE> [--outfile <OUTFILE>] [--ir-path <ir-path...>]
將 FXT-FILE 替換為追蹤檔的路徑。根據預設，在符號化之後，系統會覆寫原始追蹤檔案中的追蹤記錄。指定 OUTFILE 引數會將追蹤記錄寫入指定檔案。
ir-path 引數可用來提供用於符號化的特定 IR 檔案。即使沒有 Fuchsia 建構目錄，也能使用提供的 IR 檔案執行符號化作業。
您也可以使用以下指令，以符號表示個別序數：
ffx trace symbolize [--ordinal <ordinal>] [--ir-path <ir-path...>]
查看追蹤記錄類別
ffx trace start 指令可讓您選取用來收集追蹤記錄資料的類別，例如：
$ ffx trace start --categories "kernel,kernel:arch"
如要查看 Fuchsia 裝置上所有可用的追蹤記錄類別，請執行下列指令：
ffx trace list-categories
這個指令會輸出類似以下的輸出內容：
$ ffx trace list-categories
Known Categories:
- app - Generic application traces
- benchmark - Benchmark traces
- cpu - several, run xyz for the list
- gfx - Graphics & Compositor
- input - Input system
- kernel - All kernel trace events
- kernel:arch - Kernel arch events
Default Categories:
- app
- audio
- benchmark
- blobfs
如要進一步瞭解類別，請參閱「附錄」中的類別和類別群組。
查看追蹤記錄提供者
如要查看 Fuchsia 裝置上所有可用的追蹤記錄提供者，請執行下列指令：
ffx trace list-providers
這個指令會輸出類似以下的輸出內容：
$ ffx trace list-providers
Trace providers:
- ktrace_provider
附錄
類別和類別群組
ffx trace start 指令支援特殊語法，可更精確地控制啟用或停用特定類別：
結尾的星號 (
*) 會執行前置字串比對。舉例來說，
kernel*會啟用kernel:meta, kernel:sched。斜線 (
/) 會將類別限制在特定追蹤提供者。例如，
archivist.cm/packet只會為archivist追蹤提供者啟用封包類別。
ffx trace start 也支援類別群組，這類群組是加上 # 前置字元標示的預先定義類別清單。舉例來說，#chrome_nav (展開為 loading、net、netlog、navigation 和 browser) 會指定與資源載入和網頁瀏覽相關的所有事件，而 #default 則代表一組預設類別。
執行 ffx trace start 時，可以一併指定類別群組和類別。例如，下列指令會啟用所有預設類別和 my_cat 類別：
$ ffx trace start --categories #default,my_cat
如要查看主機上完整的類別群組清單，請執行下列指令：
ffx config get -s all trace.category_groups
您可以使用 ffx config set 指令設定自訂類別群組。如果您要為一組常用的類別定義自訂類別群組，請執行類似下方的指令：
$ ffx config set trace.category_groups.audiovisual '["audio", "gfx"]'
上述範例指令定義了新的自訂類別群組 #audiovisual。
Chrome 和 WebEngine 類別群組
Chrome 專屬類別群組可讓從 Chrome 和 WebEngine 收集追蹤資訊。
Chrome 類別群組清單如下：
#chrome_input：輸入處理事件。#chrome_ipc_flows：Mojo IPC 轉送事件。#chrome_js_exec：JavaScript (V8) 事件。#chrome_nav：資源載入、頁面導覽和瀏覽器事件。#chrome_task_sched：非同步工作排程和分派事件。#chrome_ui_render：Chrome UI 事件 (瀏覽器使用者體驗、瀏覽器小工具、合成器和 GPU)。#chrome_web_content_render：內容轉譯事件 (閃爍、合成器和 GPU)。
所有 Chrome 類別群組都包含 toplevel 和 toplevel.flow 類別，其涵蓋各種基本 Chrome 事件 (例如非同步工作排程)。
指定類別時，您可以合併 Chrome 類別和 Fusia 類別。舉例來說，下列指令會收集 Chrome 內容轉譯的追蹤資料，以及 Zircon 核心排程器活動：
$ ffx trace start --categories kernel:sched,#chrome_web_content_render
緩衝模式選項
--buffering-mode 旗標可讓您決定緩衝區填滿時會發生什麼事。
可採用的選項包括：
oneshot：寫入緩衝區直到滿載，然後忽略所有額外的追蹤記錄事件。(這是預設選項)。circular：寫入緩衝區直到滿載為止，然後使用新事件取代舊事件。streaming：在追蹤記錄事件送達時，將追蹤事件轉送至追蹤記錄管理工具。streaming選項提供額外的緩衝區空間，並因偶爾將事件傳送至追蹤記錄管理工具的處理序間通訊 (IPC) 而減少一些負擔。
下列指令會執行可用緩衝區大小 (64 MB) 最大的追蹤記錄，並以新事件覆寫舊事件：
$ ffx trace start --buffer-size 64 --buffering-mode circular
與互動模式類似，按下 Enter 鍵即可停止追蹤記錄。
下列指令會以緩衝區中的新事件覆寫舊事件，並在事件發生時停止追蹤記錄：
$ ffx trace start --buffer-size 64 --buffering-mode circular --trigger 'myexample:terminate'
追蹤的程式碼必須設為觸發事件，上述指令才能正常運作。