このページは Cloud Translation API によって翻訳されました。

perfetto

perfetto は、Android Debug Bridge（ADB）を介して Android デバイスからパフォーマンス情報を収集するためのツールです。perfetto ツールを呼び出すには、adb shell perfetto ... コマンドを使用します。perfetto は、さまざまなソースを使用してデバイスから次のようなパフォーマンストレースを収集します。

ftrace: カーネルからの情報
atrace: サービスとアプリでのユーザー空間アノテーション
heapprofd: サービスとアプリのネイティブメモリ使用情報

このページでは、perfetto を呼び出して、必要な出力を生成するための設定方法について説明します。詳しくは、perfetto のドキュメントをご覧ください。

構文

このセクションでは、ADB を使用して各種のモードで perfetto を呼び出し、トレースを生成する方法について説明します。

データソースの選択

perfetto には、トレースの記録に使用するデータソースを決定するモードが 2 つあります。

ライトモード: データソースのサブセット（具体的には atrace と ftrace）のみを選択できます。ただし、このモードでは systrace に似たインターフェースが提供されます。
通常モード: プロトコルバッファで構成を取得します。atrace および ftrace とは異なるデータソースを使用して、perfetto の機能をさらに活用できます。

全般オプション

perfetto のどちらのモードでも利用できるオプションを次の表に示します。

表 1. 一般的に利用できる perfetto ツールオプションのリスト。

オプション	説明
`--background \| -d`	`perfetto` は直ちにコマンドラインインターフェースを終了し、バックグラウンドでトレースを記録し続けます。
`--background-wait \| -D`	`--background` と似ていますが、すべてのデータソースが起動するのを待ってから（最大 30 秒）、コマンドラインインターフェースを終了します。確認応答が成功した場合は終了コードがゼロになり、成功しなかった場合（エラーまたはタイムアウト）はゼロ以外の値になります。
`--alert-id`	このトレースをトリガーしたアラートの ID。
`--config-id`	トリガー構成の ID。
`--config-uid`	構成を登録したアプリの UID。
`--subscription-id`	このトレースをトリガーしたサブスクリプションの ID。
`--out OUT_FILE \| -o OUT_FILE`	必要に応じて出力トレースファイルのパスを指定します（`stdout` の場合は `-`）。 `perfetto` は、前のフラグで記述したファイルに出力を書き込みます。出力形式は、AOSP の `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）またはギガバイト単位（MB）で指定します。デフォルトパラメータは `--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

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`	構成ファイルへのパスを指定します。通常モードでは、構成プロトコルバッファにエンコードされる構成もあります。このファイルは、AOSP の `trace_config.proto` で定義されているプロトコルバッファスキーマに従う必要があります。 AOSP の `data_source_config.proto` で定義されている `TraceConfig` の `DataSourceConfig` メンバーを使用して、データソースを選択して構成します。
`--txt`	構成ファイルを `pbtxt` として解析するよう `perfetto` に指示します。このフラグはローカルテストのみを想定しているため、本番環境で有効にすることはおすすめしません。

--config CONFIG_FILE | -c CONFIG_FILE

構成ファイルへのパスを指定します。通常モードでは、構成プロトコルバッファにエンコードされる構成もあります。このファイルは、AOSP の trace_config.proto で定義されているプロトコルバッファスキーマに従う必要があります。

AOSP の data_source_config.proto で定義されている TraceConfig の DataSourceConfig メンバーを使用して、データソースを選択して構成します。

--txt 構成ファイルを pbtxt として解析するよう perfetto に指示します。このフラグはローカルテストのみを想定しているため、本番環境で有効にすることはおすすめしません。

サポートされるデータソース

このセクションでは、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 にあります。