Perfetto

perfetto 這項工具可讓您透過 Android Debug Bridge (ADB) 收集 Android 裝置的效能資訊。perfetto 會使用各種來源從裝置收集效能追蹤記錄，例如：

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

本頁說明如何呼叫 perfetto 並設定以產生所需輸出內容。

語法

本節說明如何使用 ADB 呼叫 perfetto 並產生追蹤記錄。

資料來源選項

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

淺色模式：只能選取部分資料來源 (具體來說是 atrace 和 ftrace)；不過這個模式提供類似 systrace 的介面。
一般模式：您可以在通訊協定緩衝區中取得這個模式的設定，並使用不同於 atrace 和 ftrace 的資料來源，充分運用 perfetto 的強大功能。

本節說明 perfetto 使用上述各個模式產生追蹤記錄時需要的語法。

一般選項

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

選項	說明
`--background \| -d`	Perfetto 會立即結束指令列介面，並在背景中繼續記錄您的追蹤記錄。
`--out OUT_FILE \| -o OUT_FILE`	指定輸出追蹤記錄檔的所需路徑，或如果是標準輸出，則為 -。`perfetto` 會將輸出內容寫入上述標記中描述的檔案。輸出內容格式會以 Android 開放原始碼計畫 `trace.proto` 中定義的格式編譯。
`--upload`	完成後，將追蹤記錄傳送至 proto 追蹤設定中 `IncidentReportConfig` 訊息指定的套件。
`--no-guardrails`	在測試期間啟用 `--upload` 標記時，停用防止過度使用資源的防護功能。
`--reset-guardrails`	重設防護措施的持續狀態並結束防護 (測試用)。
`--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 時的可用選項。

選項	說明
`--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` 只會使用記憶體內環形緩衝區。

接下來則是事件說明符清單

事件	說明
`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

事件

說明

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 時的可用選項。

選項	說明
`--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
檔案系統事件：
- ext4
- f2fs
- block
ATrace 事件

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

處理程序統計資料

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

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

perfetto 產生的資料包括：

整個系統
- /proc/meminfo
- /proc/vmstat
- /proc/stat
每項程序
- /proc/<pid>/status
- /proc/<pid>/oom_score_adj

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

Heapprofd

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

您可以在 DataSourceConfig 中設定 heapprofd_config 來啟用這個來源。

這項操作會產生 ProfilePackets。其中包括呼叫堆疊的 Java 堆疊框。

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

其他來源

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

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