記錄追蹤記錄進行效能分析

ffx trace 指令可記錄 Fuchsia 裝置的診斷追蹤資料。這項資料可用於測量及偵錯效能問題、瞭解執行緒、程序和元件之間的互動，以及將整個系統視覺化。

新增 Fuchsia 追蹤記錄事件

如需在程式碼中加入 Fuchsia 追蹤記錄的完整端對端指南，請參閱「Fuchsia 追蹤記錄教學課程」。

概念

Fuchsia 追蹤系統提供機制，可從 Fuchsia 裝置上的使用者空間程序和 Zircon 核心收集、匯總及以視覺化方式呈現診斷追蹤資訊。追蹤系統由追蹤管理工具、記憶體緩衝區和一或多個追蹤供應器組成。「追蹤記錄供應器」是可在裝置上產生追蹤記錄資料的元件，一個系統可以有多個追蹤記錄供應器。(如要將元件註冊為追蹤記錄提供者，請參閱「註冊追蹤記錄提供者」一文)。

ffx trace start 指令會將追蹤輸出內容儲存為主體機器上的 .fxt 檔案。您可以在 Perfetto 檢視器中開啟這個檔案，或將檔案上傳至 Google Cloud Storage (GCS)，然後透過直接網址查看及共用。(如要進一步瞭解 Perfetto，請參閱這個 Perfetto 說明文件網站)。

根據預設，ffx trace start 指令會嘗試從一組預先定義的追蹤類別收集追蹤資料 (執行 ffx trace start --help 即可查看預設類別)。不過，ffx trace start 也可讓您選取追蹤記錄類別，以收集追蹤記錄資料。

Fuchsia 裝置一次只能執行一個追蹤工作階段，且輸出檔案只能記錄單一追蹤記錄。在下列範例中，所有 輸出檔案預設都會trace.fxt位於執行 ffx trace 的目錄中， 且所有目標裝置預設都會是當時連線至主機 的 可用 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。

在背景模式下，追蹤記錄可能會隨著時間變得非常龐大。視選取的緩衝模式而定，這項設定會產生不同影響：

  • oneshot (預設)：緩衝區填滿後，後續事件會遭到捨棄。系統只會記錄最早的事件。
  • circular：緩衝區填滿並輪替時，字串表格可能會遺失，導致追蹤記錄損毀且無法讀取 (請參閱 b/484012306)。
  • streaming：事件會持續轉送至追蹤記錄管理工具。 一般來說，建議使用這個模式進行背景追蹤，以免捨棄資料或損毀追蹤記錄。

如要啟動背景追蹤，請執行下列指令：

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>

使用 alert:action 語法將 TRIGGER 替換為動作，例如：

$ 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 標記選取要停止的追蹤記錄，然後停止與輸出檔案相關聯的追蹤記錄。

傳遞 --compressed，即可在主機上使用 Zstandard 壓縮追蹤記錄 (儲存至 trace.fxt.zst)。 傳遞 --upload，即可在停止時自動將追蹤記錄資料上傳至 GCS。

這個指令會輸出類似以下的結果：

$ 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.

如要分析這次執行收集到的結果，請參閱「以視覺化方式呈現追蹤記錄結果」或「將追蹤記錄上傳至 Google Cloud Storage」。

記錄壓縮後的追蹤記錄

追蹤記錄 (特別是在 streaming 緩衝模式下，或長時間記錄的追蹤記錄) 可能會成長至數百 MB 或 GB。這可能會導致追蹤構件超出儲存空間或測試執行元件上傳限制 (例如 ResultDB 的每個構件 640 MB 限制)。

如要在主體機器上保留以 Zstandard 壓縮的追蹤記錄檔，請將 --compressed 旗標傳遞至 ffx trace start 或 ffx trace stop：

ffx trace start --compressed

或是停止背景追蹤時：

ffx trace stop --compressed

啟用「--compressed」後：

  • 輸出檔案預設為目前目錄中的 trace.fxt.zst (或透過 --output 指定的自訂路徑)。
  • ffx trace 會即時解壓縮追蹤記錄，執行 FIDL IPC 符號化和類別檢查 (post_process)，然後使用 Zstandard 重新壓縮符號化追蹤記錄。
  • 產生的 .fxt.zst 檔案可直接在 Perfetto 檢視器中開啟，或使用 fx perf-analyze 進行分析，不需手動解壓縮。

將追蹤記錄上傳至 Google Cloud Storage

您可以將記錄的追蹤記錄檔案上傳至 Google Cloud Storage (GCS)，產生直接連結，以便在 Perfetto 檢視器中查看及分享追蹤記錄。

在擷取追蹤記錄時上傳

如要在停止互動式追蹤工作階段時自動上傳追蹤記錄，請將 --upload 標記傳遞至 ffx trace start：

ffx trace start --upload

停止追蹤 (按下 Enter 或達到 --duration) 後，追蹤記錄就會完成並上傳至 GCS：

$ ffx trace start --upload
Tracing started successfully on "fuchsia-5254-0063-5e7a".
Writing to /Users/alice/trace.fxt
Press <enter> to stop trace.

Shutting down recording and writing to file.
Tracing stopped successfully on "fuchsia-5254-0063-5e7a".
Results written to /Users/alice/trace.fxt
Uploading trace to gs://fuchsia-trace-viewer-traces...
Trace uploaded successfully!

View in Perfetto Trace Viewer:
  https://fuchsia-trace-viewer.corp.goog/trace/b94d27b9

ffx trace stop --upload

上傳現有追蹤記錄檔

如果您已在主體機器上錄製 .fxt 追蹤記錄檔，可以使用 ffx trace upload 上傳：

ffx trace upload [FILE_PATH] [--bucket BUCKET_NAME]

如果省略 FILE_PATH，系統會預設為 trace.fxt。

例如：

$ ffx trace upload /Users/alice/trace.fxt
Uploading trace to gs://fuchsia-trace-viewer-traces...
Trace uploaded successfully!

View in Perfetto Trace Viewer:
  https://fuchsia-trace-viewer.corp.goog/trace/b94d27b9

指定自訂 GCS bucket

根據預設，追蹤記錄會上傳至 fuchsia-trace-viewer-traces GCS 值區。您可以使用 --bucket 選項指定其他 bucket：

ffx trace start --upload --bucket <BUCKET_NAME>

或是上傳現有追蹤記錄時：

ffx trace upload [FILE_PATH] --bucket <BUCKET_NAME>

GCS 驗證和設定

驗證

如要將追蹤記錄上傳至 Google Cloud Storage，必須先通過 Google Cloud 驗證。請確認您已透過應用程式預設憑證 (ADC) 或 gcloudCLI 進行驗證：

gcloud auth application-default login

預設設定

您可以使用 ffx config 自訂預設 GCS bucket 和追蹤檢視器網址：

  • trace.gcs_bucket：上傳追蹤記錄的預設 GCS bucket。 posix-terminal ffx config set trace.gcs_bucket <BUCKET_NAME>
  • trace.viewer_url：Perfetto 追蹤檢視器執行個體的基準網址 (預設為 https://fuchsia-trace-viewer.corp.goog)。 posix-terminal ffx config set trace.viewer_url <VIEWER_URL>

以圖表呈現追蹤記錄結果

追蹤完成並建立 .fxt 檔案後，您可以透過下列兩種方式查看追蹤記錄：

  • 透過網址開啟：如果追蹤記錄已上傳至 GCS (使用 --upload 或 ffx trace upload)，請前往指令輸出中產生的 Perfetto 追蹤記錄檢視器網址。
  • 開啟本機檔案：
    1. 在網路瀏覽器中前往 Perfetto 檢視器網站。
    2. 按一下導覽列中的「Open trace file」。
    3. 從主體機器選取 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

其他追蹤指南

如需在 Fuchsia 中使用追蹤功能的其他指南，請參閱 Fuchsia 追蹤指南。

附錄

類別和類別群組

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 事件 (瀏覽器 UX、瀏覽器小工具、合成器和 GPU)。
  • #chrome_web_content_render：內容轉譯事件 (Blink、合成器和 GPU)。

所有 Chrome 類別群組都包含 toplevel 和 toplevel.flow 類別，涵蓋各種基本 Chrome 事件，例如非同步工作排程。

指定類別時，您可以合併 Chrome 類別和 Fuchsia 類別。舉例來說，下列指令會收集 Chrome 內容算繪的追蹤資料，以及 Zircon 核心排程器活動：

$ ffx trace start --categories kernel:sched,#chrome_web_content_render

緩衝模式選項

您可以使用 --buffering-mode 標記，決定緩衝區填滿時的處理方式。

可採用的選項包括：

  • oneshot：寫入緩衝區，直到緩衝區已滿，然後忽略所有其他追蹤事件。(這是預設選項)。

  • circular：寫入緩衝區，直到緩衝區已滿，然後以新事件取代舊事件。

  • streaming：將追蹤事件轉送至追蹤管理工具。

    「streaming」選項提供額外的緩衝區空間，但由於偶爾會進行 IPC，將事件傳送至追蹤管理員，因此會產生一些額外負擔。如要擷取大型追蹤記錄，一般建議使用這個模式，而非非常大的緩衝區。

下列指令會執行追蹤作業，並使用 32 MB 的緩衝區，以新事件覆寫舊事件：

$ ffx trace start --buffer-size 32 --buffering-mode circular

與互動模式類似，按下 Enter 鍵即可停止追蹤。

下列指令會以緩衝區中的新事件覆寫舊事件，並在事件發生時停止追蹤：

$ ffx trace start --buffer-size 32 --buffering-mode circular --trigger 'myexample:terminate'

如要讓上述指令正常運作，追蹤的程式碼必須已設定為觸發事件。