perfetto

perfetto は Android Debug Bridge（ADB） を介して Android デバイスからパフォーマンス情報を収集できるツールです。perfetto は、デバイスからパフォーマンス トレースを収集するときに、次のような複数のソースを使用します。

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

このページでは、perfetto を呼び出して、必要な出力を生成するための設定方法について説明します。

構文

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

データソースの選択

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

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

このセクションでは、perfetto が上記の各モードを使用してトレースを生成する際に必要な構文について説明します。

全般オプション

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

オプション 説明
--background | -d Perfetto はすぐにコマンドライン インターフェースを終了し、バックグラウンドでトレースを記録し続けます。
--out OUT_FILE | -o OUT_FILE 出力トレース ファイルへの目的のパスを指定します。stdout に出力する場合は「-」を指定します。 perfetto は、上記のフラグで指定されているファイルに出力を書き込みます。出力時の形式は、AOSP trace.proto で定義された形式になります。
--dropbox TAG DropboxManager API を介して、指定したタグを使ってトレースをアップロードします。
--no-guardrails テスト中に --dropbox フラグが有効な場合に、過剰なリソースの使用に対する保護を無効にします。
--reset-guardrails ガードレールの永続的な状態をリセットし、終了します（テスト用）。
--query サービスの状態に関してクエリを実行し、判読可能なテキストとして出力します。
--query-raw --query と同様ですが、tracing_service_state.proto. のプロトコル エンコードされた未加工のバイト列を出力します。
--help | -h perfetto ツールのヘルプテキストを出力します。

ライトモード

ライトモードで perfetto を使用する一般的な構文は次のとおりです。

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

次の表に、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 はメモリ内のリングバッファのみを使用します。

次に、イベント指定子の一覧を示します。

イベント 説明
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

次の表に、通常モードで 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 のバージョン、カーネルによっては、さらに多くのイベントが利用できます。詳しくは、config protos をご覧ください。

プロセスの統計情報

プロセス統計データソースを使用すると、システムと個々のプロセスについて収集されたカウンタを取得できます。

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

profetto が生成するデータには以下が含まれます。

使用しているデバイス、OS のバージョン、カーネルによっては、さらに多くのイベントが利用できます。詳しくは、sys_stats と process_stats の構成プロトタイプをご覧ください。

Heapprofd

Heapprofd では、ネイティブ メモリ使用量とその原因をサンプリングできます。

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

これにより、ProfilePackets が生成され、 コールスタックの Java フレームが含まれます。

heapprofd の使用方法に関する追加情報は、perfetto.dev にあります。

その他のソース

使用しているデバイス、OS のバージョン、カーネルによっては、より多くのデータソースが使用できる場合があります。詳しくは、データソースの config protos をご覧ください。

perfetto に関する追加情報は、perfetto.dev にあります。