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

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

新增 Fuchsia 追蹤記錄事件

如需完整的端對端指南,瞭解如何在程式碼中加入 Fuchsia 追蹤功能,請參閱「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 檢視器中開啟檔案,以便以視覺化方式呈現追蹤記錄結果。

請完成下列步驟:

  1. 透過網路瀏覽器前往 Perfetto 檢視器網站。
  2. 按一下導覽列的「Open trace file」
  3. 從主體機器選取 trace.fxt 檔案。

將 FIDL 追蹤記錄符號化

如果追蹤記錄的類型包含 kernel:ipc 類別,.fxt 追蹤記錄檔就會包含數個與在追蹤記錄期間進行 FIDL 呼叫相對應的頻道訊息事件。這些管道訊息只會包含與 FIDL 呼叫相關聯的序數,FIDL 是所呼叫方法的 SHA-256 雜湊。

Fuchsia 建構目錄包含名稱結尾為 .fidl.json 的檔案。這些檔案包含在 Fuchsia 建構期間產生,將一般轉換為對應 FIDL 方法所需的資訊。只要可用的 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 (展開為 loadingnetnetlognavigationbrowser) 可用來指定與載入資源及瀏覽頁面相關的所有事件,而 #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 類別群組都有 topleveltoplevel.flow 類別,這些類別涵蓋各種基本的 Chrome 事件,例如非同步工作排程。

指定類別時,您可以將 Chrome 類別與 Fuchsia 類別合併。舉例來說,以下指令會連同 Zircon 核心排程器活動,收集 Chrome 內容轉譯的追蹤記錄資料:

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

緩衝模式選項

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

可採用的選項包括:

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

  • circular:寫入緩衝區,直到緩衝區已滿,然後將舊事件取代為新事件。

  • streaming:將追蹤事件轉送至到達的追蹤管理工具。

    streaming 選項會提供額外的緩衝區空間,但由於偶爾會傳送事件至追蹤管理員,因此會產生一些額外的開銷。

下列指令會使用可用的最大緩衝區大小 (64 MB) 執行追蹤記錄,並以新事件覆寫舊事件:

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

互動模式類似,按下 Enter 鍵即可停止追蹤記錄。

下列指令會使用緩衝區中的新事件覆寫舊事件,並在事件發生時停止追蹤記錄:

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

為使上述指令生效,您必須先設定追蹤程式碼,才能觸發事件。