perfetto

perfetto 是一項工具，可讓您透過 Android Debug Bridge (ADB) 收集 Android 裝置的效能資訊。使用 adb shell perfetto ... 指令叫用 perfetto 工具。perfetto 會使用多個來源從裝置收集效能追蹤記錄，例如：

  • 使用 ftrace 取得核心資訊
  • 使用 atrace 取得服務與應用程式中的使用者空間註解
  • 使用 heapprofd 取得服務與應用程式的原生記憶體用量資訊

本頁說明如何呼叫 perfetto 並設定以產生所需的輸出內容。詳情請參閱 perfetto 說明文件。

語法

本節說明如何使用 ADB 針對不同模式呼叫 perfetto 並產生追蹤記錄。

選取資料來源

perfetto 包含下列兩個模式，用於決定要用來記錄追蹤記錄的資料來源：

  • 淺色模式：僅選取部分資料來源，特別是 atrace 和 ftrace。不過，這個模式提供與 systrace 類似的介面。
  • 標準模式：在通訊協定緩衝區中取得設定，並且藉由與 atrace 和 ftrace 不同的資料來源，讓您使用更多 perfetto 的功能。

一般選項

下表列出在這兩種模式中使用 perfetto 的可用選項。

表 1. 一般可用的 Perfetto 工具選項清單。

選項 說明
--background |
-d 		perfetto 會立即結束指令列介面，並在背景中繼續記錄您的追蹤記錄。
--background-wait | -D 與 --background 一樣，但是會等待所有資料來源 (最多 30 秒) 才會離開。如果收到成功確認，離開事件代碼為 0，否則傳回不為零的值 (錯誤或逾時)。
--alert-id 觸發此追蹤記錄的警示 ID。
--config-id 觸發設定的 ID。
--config-uid 註冊該設定的應用程式 UID。
--subscription-id 觸發此追蹤記錄的訂閱項目 ID。
--out OUT_FILE |
-o OUT_FILE

指定輸出追蹤檔的所需路徑，或者如果為 stdout，則為 -。perfetto 會將輸出內容寫入上述標記中描述的檔案。輸出內容格式會以 Android 開放原始碼計畫 trace.proto 中定義的格式編譯。

注意：您必須指定輸出檔案的完整路徑名稱。一般來說，檔案應寫入 /data/misc/perfetto-traces 資料夾。
--upload 完成後，將追蹤記錄傳送至 proto 追蹤設定中 IncidentReportConfig 訊息指定的套件。
--no-guardrails 在測試期間啟用 --upload 標記時，停用防止過度使用資源的防護功能。
--reset-guardrails 重設防護措施的持續狀態並結束防護 (測試用)。
--rsave-for-bugreport 如果 bugreport_score > 0 的追蹤記錄正在執行，請將追蹤記錄儲存至檔案。完成後再輸出至該路徑。
--query 查詢服務狀態，並以人類可讀的文字輸出。
--query-raw 與 --query 類似，但會輸出 tracing_service_state.proto. 的原始 proto 編碼位元組。
--help | -h 列印 perfetto 工具的說明文字。

淺色模式

在淺色模式中使用 perfetto 的一般語法如下：

 adb shell perfetto [ --time TIMESPEC ] [ --buffer SIZE ] [ --size SIZE ]
             [ ATRACE_CAT | FTRACE_GROUP/FTRACE_NAME | FTRACE_GROUP/* ]...
             --out FILE

下表列出在淺色模式中使用 perfetto 時的可用選項。

表 2. 使用淺色模式時可用的 perfetto 工具選項清單。

選項 說明
--time TIME[s|m|h] |
-t TIME[s|m|h] 		以秒、分鐘或小時為單位指定追蹤記錄時間長度。舉例來說，--time 1m 會將追蹤記錄時間長度指定為 1 分鐘。預設時間長度為 10 秒。
--buffer SIZE[mb|gb] |
-b SIZE[mb|gb] 		以 MB 或 GB 為單位指定環形緩衝區空間大小。預設參數為 --buffer 32mb。
--size SIZE[mb|gb] |
-s SIZE[mb|gb] 		以 MB 或 GB 為單位指定檔案大小上限。根據預設，perfetto 只會使用記憶體的環形緩衝區。
--app | -a Android (atrace) 應用程式名稱

這些選項後面接有事件指定詞清單：

表 3. 淺色模式的事件指定詞清單。

事件 說明
ATRACE_CAT 指定要追蹤記錄的 atrace 類別。舉例來說，以下指令使用 atrace 追蹤視窗管理員：
    adb shell perfetto --out FILE wm

如要記錄其他類別，請參閱這份 atrace 類別清單。

FTRACE_GROUP/FTRACE_NAME 指定要追蹤記錄的 ftrace 事件。例如，下列指令會追蹤 sched/sched_switch 事件： 
      adb shell perfetto --out FILE sched/sched_switch

標準模式

在一般模式中使用 perfetto 的一般語法如下：

 adb shell perfetto [ --txt ] --config CONFIG_FILE --out FILE

下表列出在一般模式中使用 perfetto 時的可用選項。

表 4. 使用一般模式時可用的 perfetto 工具選項清單。

選項 說明
--config CONFIG_FILE | -c CONFIG_FILE 指定設定檔的路徑。在一般模式下，部分設定可能會在設定通訊協定緩衝區進行編碼。這個檔案必須符合 Android 開放原始碼計畫 trace_config.proto 中定義的通訊協定緩衝區結構定義。

如 Android 開放原始碼計畫 data_source_config.proto 中所定義，請使用 TraceConfig 的 DataSourceConfig 成員選取及設定資料來源。
--txt 指示 perfetto 將設定檔剖析為 pbtxt。這項標記僅適用於本機測試，因此不建議針對正式版啟用。

支援的資料來源

本節說明 perfetto 用來產生追蹤記錄的不同來源。

ftrace

ftrace 資料來源可讓 perfetto 從核心取得事件。

在 DataSourceConfig 中設定 ftrace_config 來啟用這個來源。

可啟用的事件包括：

  • 安排活動：

    • sched/sched_switch
    • sched/sched_wakeup
    • sched/sched_wakeup_new
    • sched/sched_process_exec
    • sched/sched_process_exit
    • sched/sched_process_fork
    • sched/sched_process_free
    • sched/sched_process_hang
    • sched/sched_process_wait

  • 檔案系統事件：

  • atrace 項活動

視您的裝置、OS 版本和核心而定，您或許可以使用更多的事件。詳情請參閱設定 proto。

處理程序統計資料

處理程序統計資料的資料來源可讓您取得與系統和個別程序相關的輪詢計數器。

在 DataSourceConfig 中設定 process_stats_config 和 sys_stats_config 來啟用這個來源。

perfetto 產生的資料包括：

視您的裝置、OS 版本和核心而定，您或許可以使用更多事件。詳情請參閱 sys_stats 和 process_stats 的設定 proto。

heapprofd

heapprofd 可讓您取樣原生記憶體的使用原因。

在 DataSourceConfig 中設定 heapprofd_config 來啟用這個來源。這項設定會產生 ProfilePackets，包括呼叫堆疊的 Java 框架。

如要進一步瞭解如何使用 heapprofd，請前往 perfetto.dev。

其他來源

視您的裝置、OS 版本和核心而定，您或許可以使用更多資料來源。詳情請參閱資料來源設定 proto。

如要進一步瞭解 perfetto，請前往 perfetto.dev。