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

通常モード

通常モードで 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 に指示します。このフラグはローカルテストのみを想定しているため、本番環境で有効にすることはおすすめしません。

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

このセクションでは、perfetto がトレースの生成に使用するさまざまなソースについて説明します。

ftrace

ftrace データソースを使用すると、perfetto はカーネルからイベントを取得できます。

このソースを有効にするには、DataSourceConfig で ftrace_config を設定します。

有効にできるイベントは次のとおりです。

使用しているデバイス、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 にあります。