adb コマンドでトレースをキャプチャする

Winscope トレースは、デバッグビルド（userdebug ビルドと eng ビルド）の adb コマンドラインで収集できます。adb で Winscope トレースを収集する前に、adb root を実行します。

Android 15 以降では、Winscope トレースは Perfetto に統合され、Perfetto コマンドラインを使用して収集されます。各 Winscope トレースは Perfetto データソースであり、それぞれ独自の構成を使用します。個別または 1 回のトレース セッションで構成を有効化できます。

Android 14 以前では、各 Winscope トレースに異なるコマンドがあり、それぞれ個別に収集できます。詳しくは、Android 14 以前でトレースをキャプチャするをご覧ください。

WindowManager

この種類のトレースには、android.windowmanager というデータソース名を使用します。

構成オプション

  • ログレベル（log_level）: ログの詳細度を指定します。サポートされている値は次のとおりです。

    • LOG_LEVEL_VERBOSE: 最も情報量が多く、すべての要素をログに記録します。
    • LOG_LEVEL_DEBUG: すべての要素をログに記録しますが、構成データをすべて書き込みするわけではありません。
    • LOG_LEVEL_CRITICAL: 表示可能な要素のみをログに記録し、パフォーマンス オーバーヘッドは最小となります。

  • ログの頻度（log_frequency）: 項目をログに記録する頻度を定義します。

    • LOG_FREQUENCY_FRAME: フレームが commit されるときのトレースの状態のスナップショット。
    • LOG_FREQUENCY_TRANSACTION: トランザクションが commit されるたびに作成されるトレースの状態のスナップショット。
    • LOG_FREQUENCY_SINGLE_DUMP: データソースが開始されるときのトレースの単一の状態のスナップショット。

構成値の詳細については、WindowManager をご覧ください。

例

以下に、adb 用の WindowManager トレースの種類の例を示します。

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
EOF

ProtoLog

この種類のトレースには、android.protolog というデータソース名を使用します。

構成オプション

トレースモード（tracing_mode）: 使用するログ構成を決定します。

  • DEFAULT: group_overrides で指定されたロググループとログレベルのみをトレースします。
  • ENABLE_ALL: group_overrides で指定されていないすべてのロググループとログレベルをトレースします。

最小ログレベル（default_log_from_level）: 設定した場合、グループのオーバーライドが指定されない限り、このログレベル以上のメッセージがすべてトレースされます。たとえば、すべてのログを有効化することなく警告とエラーをすべてログに記録するために使用されます。サポートされている値は次のとおりです。

  • PROTOLOG_LEVEL_DEBUG
  • PROTOLOG_LEVEL_VERBOSE
  • PROTOLOG_LEVEL_INFO
  • PROTOLOG_LEVEL_WARN
  • PROTOLOG_LEVEL_ERROR
  • PROTOLOG_LEVEL_WTF

グループのオーバーライド（group_overrides）: 各 ProtoLog グループのログレベルを手動で設定できます。各グループには以下が含まれます。

  • name: Android ソースコードで使用される ProtoLog グループ名。
  • log_from: default_log_from_level と同じですが、現在のグループに対してのみ指定されます。

  • collect_stacktrace: true に設定すると、トレースされるグループ内の各 ProtoLog メッセージのスタック トレースが収集されます。

例

以下に、adb 用の ProtoLog トレースの種類の例を示します。

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: DEFAULT
              default_log_from_level: PROTOLOG_LEVEL_WARN
              group_overrides: {
                 group_name: "WM_SHELL_STARTING_WINDOW"
                 log_from: PROTOLOG_LEVEL_DEBUG
                 collect_stacktrace: true
              }
           }
       }
   }
EOF

入力

この種類のトレースには、android.input.inputevent というデータソース名を使用します。

構成オプション

トレースモード（trace_mode）: プライバシーの保護に関するルールを使用して入力トレースを開始すべきか、またはすべての入力イベントを記録するかどうかを決定します。

  • TRACE_MODE_TRACE_ALL: 処理されるコンテキストにかかわらず、システムが処理する入力イベントをすべて記録します。
  • TRACE_MODE_USE_RULES: この設定で定義したトレースルールを使用してトレースするイベントを指定します。トレースのルールを指定する方法について詳しくは、android_input_event_config.proto をご覧ください。

例

以下に、adb 用の入力トレースの種類の例を示します。

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
EOF

SurfaceFlinger（レイヤ）

この種類のトレースには、android.surfaceflinger.layers というデータソース名を使用します。

構成オプション

トレースモード（mode）: 項目をログに記録する頻度を定義します。

  • MODE_ACTIVE: レイヤのスナップショットをトレースします。レイヤが変更されるたびにスナップショットが作成されます。
  • MODE_GENERATED: SurfaceFlinger の内部リングバッファに保存されているトランザクションからレイヤのスナップショットを生成します。このデータソースがフラッシュされると、レイヤのスナップショットが生成されます。
  • MODE_DUMP: レイヤの単一スナップショットをトレースします。
  • MODE_GENERATED_BUGREPORT_ONLY: MODE_GENERATED と同様ですが、トレースがフラッシュされるたびではなく、バグレポートの取得時にのみレイヤのスナップショット生成をトリガーします。

トレースフラグ（trace_flags）:

  • TRACE_FLAG_INPUT: サーフェスに入力データがある場合、入力ウィンドウの詳細を追跡します。
  • TRACE_FLAG_COMPOSITION: 合成タイプと表示領域をトレースします。

  • TRACE_FLAG_EXTRA: オフスクリーン レイヤを含む追加のサーフェス メタデータをトレースします。

  • TRACE_FLAG_HWC: 構造化されていないハードウェアの構成者の追加のメタデータをトレースします。

  • TRACE_FLAG_BUFFERS: サーフェス上のバッファの変更をすべてトレースするよう SurfaceFlinger を構成します。デフォルトでは、SurfaceFlinger はジオメトリの変更が発生したときにのみ新しい状態をトレースします。

  • TRACE_FLAG_VIRTUAL_DISPLAYS: トレース内の仮想ディスプレイのレイヤを含めます。

例

以下に、adb 用の SurfaceFlinger トレースの種類の例を示します。

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.layers"
           surfaceflinger_layers_config: {
              mode: MODE_ACTIVE
              trace_flags: TRACE_FLAG_INPUT
              trace_flags: TRACE_FLAG_COMPOSITION
              trace_flags: TRACE_FLAG_HWC
              trace_flags: TRACE_FLAG_BUFFERS
              trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
           }
       }
   }
EOF

異なる構成値の意味について詳しくは、SurfaceFlinger をご覧ください。

シェルの遷移

この種類のトレースには、com.android.wm.shell.transition というデータソース名を使用します。

構成オプション

この種類のトレースには構成オプションはありません。

例

以下に、adb 用のシェル遷移のトレースの種類の例を示します。

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
EOF

SurfaceFlinger（トランザクション）

この種類のトレースには、android.surfaceflinger.transactions というデータソース名を使用します。

構成オプション

トレースモード（mode）: 項目をログに記録する頻度を定義します。

  • MODE_CONTINUOUS: SurfaceFlinger は、データソースがフラッシュされるたびに、トランザクションの内部リングバッファを書き込みます。リングバッファには、SurfaceFlinger の初期状態と最新のトランザクションが含まれています。

  • MODE_ACTIVE: SurfaceFlinger はデータソースが停止するまで、初期状態、各受信トランザクションの順に書き込みます。

例

以下に、adb 用の SurfaceFlinger トランザクション トレースの種類の例を示します。

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
EOF

IME

この種類のトレースには、android.inputmethod というデータソース名を使用します。

構成オプション

この種類のトレースには構成オプションはありません。

例

以下に、adb 用の IME トレースの種類の例を示します。

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
EOF

ViewCapture

この種類のトレースには、android.viewcapture というデータソース名を使用します。

構成オプション

この種類のトレースには構成オプションはありません。

例

以下に、adb 用の ViewCapture トレースの種類の例を示します。

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

完全な例

Perfetto を使用すると、単一構成の複数のソースからデータを収集できます。すべての Winscope トレースを 1 つのコマンドで集めることができます。

$ adb shell -t perfetto \
     -c - --txt \
     -o /data/misc/perfetto-traces/trace \
   <<EOF
   unique_session_name: "my_custom_session"
   buffers: {
       size_kb: 63488
       fill_policy: RING_BUFFER
   }
   data_sources: {
       config {
           name: "android.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
   data_sources: {
       config {
           name: "android.protolog"
           protolog_config: {
              tracing_mode: ENABLE_ALL
           }
       }
   }
   data_sources: {
       config {
           name: "android.input.inputevent"
           android_input_event_config: {
              mode: TRACE_MODE_TRACE_ALL
           }
       }
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.layers"
           surfaceflinger_layers_config: {
              mode: MODE_ACTIVE
              trace_flags: TRACE_FLAG_INPUT
              trace_flags: TRACE_FLAG_COMPOSITION
              trace_flags: TRACE_FLAG_HWC
              trace_flags: TRACE_FLAG_BUFFERS
              trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
           }
       }
   }
   data_sources: {
       config {
           name: "com.android.wm.shell.transition"
       }
   }
   data_sources: {
       config {
           name: "android.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
   data_sources: {
       config {
           name: "android.inputmethod"
       }
   }
   data_sources: {
       config {
           name: "android.viewcapture"
       }
   }
EOF

Android 14 以前でトレースをキャプチャする

次の各トレースの adb shell コマンドを実行する前に、adb root を実行します。トレースの終了時、トレース ファイルは /data/misc/wmtrace にあります。デバイスからファイルやディレクトリ（およびそのサブディレクトリ）をコピーするには、デバイスにファイルをコピーする、デバイスからファイルをコピーするをご覧ください。

WindowManager のトレース

WindowManager のトレースをキャプチャするには、以下の手順を行います。

  • トレースを有効にします。

    adb shell wm tracing start

  • トレースを無効にします。

    adb shell wm tracing stop

  • トレース キャプチャの実行中にロギングデータをファイルに保存します。

    adb shell wm tracing save-for-bugreport

  • 1 フレームごとにトレースのログを記録します。

    adb shell wm tracing frame

  • 各トランザクションのログを記録します。

    adb shell wm tracing transaction

  • 最大ログサイズを KB 単位で設定します。

    adb shell wm tracing size

  • トレース ステータスをプリントします。

    adb shell wm tracing status

  • ログレベルを critical（可視ウィンドウのみ、情報を簡略化）、trim（すべてのウィンドウ、情報を簡略化）、または all（すべてのウィンドウと情報）に設定します。

    adb shell wm tracing level

WindowManager のダンプ

WindowManager のダンプをキャプチャするには:

adb exec-out dumpsys window --proto > window_dump.winscope

ProtoLog

ProtoLog システムでは次のコマンドが使用されます。

system_server プロセス内:

  • ProtoLog を開始します。

    adb shell cmd window logging start

  • ProtoLog を停止します。

    adb shell cmd window logging stop

  • 指定されたロググループに対して ProtoLog を有効にします。

    adb shell cmd window logging enable [group...]

  • 指定されたロググループに対して ProtoLog を無効にします。

    adb shell cmd window logging disable [group...]

  • 指定されたロググループに対して Logcat ログを有効にします。

    adb shell cmd window logging enable-text [group...]

  • 指定されたロググループに対して Logcat ログを無効にします。

    adb shell cmd window logging disable-text [group...]

WMShell 内:

  • ProtoLog を開始します。

    adb shell dumpsys activity service SystemUIService WMShell

SurfaceFlinger のトレース（レイヤ）

SurfaceFlinger レイヤのトレースでは、キャプチャに Perfetto トレースを使用します。設定情報については、トレース構成を参照してください。

SurfaceFlinger レイヤのトレースの構成例を次に示します。

unique_session_name: "surfaceflinger_layers_active"
buffers: {
    size_kb: 63488
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.layers"
        surfaceflinger_layers_config: {
            mode: MODE_ACTIVE
            trace_flags: TRACE_FLAG_INPUT
            trace_flags: TRACE_FLAG_COMPOSITION
            trace_flags: TRACE_FLAG_HWC
            trace_flags: TRACE_FLAG_BUFFERS
            trace_flags: TRACE_FLAG_VIRTUAL_DISPLAYS
        }
    }
}

SurfaceFlinger レイヤのトレースを生成するためのコマンド例を次に示します。

adb shell -t perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \

SurfaceFlinger のダンプ（レイヤ）

SurfaceFlinger のダンプをキャプチャするには:

adb exec-out dumpsys SurfaceFlinger --proto > sf_dump.winscope

シェルの遷移

遷移トレースでは次のコマンドが使用されます。

system_server プロセス内:

  • トレースを開始します。

    adb shell cmd window shell tracing start

  • トレースを停止します。

    adb shell cmd window shell tracing stop

  • WMShell でトレースを開始します。

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • WMShell でトレースを停止します。

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

インプット メソッド エディタ（IME）のトレースでは次のコマンドが使用されます。

  • インプット メソッド（IM）クライアント、インプット メソッド サービス（IMS）、およびインプット メソッド マネジメント サービス（IMMS）の IME トレースを開始します。

    adb shell ime tracing start

  • IME クライアント、IMS、および IMMS のトレースを開始します。

    adb shell ime tracing stop

SurfaceFlinger（トランザクション）

SurfaceFlinger トランザクションのトレースでは、キャプチャに Perfetto トレースを使用します。設定情報については、トレース構成を参照してください。

SurfaceFlinger のアクティブなトレースの Perfetto 構成例を次に示します。

unique_session_name: "surfaceflinger_transactions_active"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_ACTIVE
        }
    }
}
write_into_file: true
file_write_period_ms: 100

SurfaceFlinger の継続的なトレースの Perfetto 構成例を次に示します。

unique_session_name: "surfaceflinger_transactions_continuous"
buffers: {
    size_kb: 1024
    fill_policy: RING_BUFFER
}
data_sources: {
    config {
        name: "android.surfaceflinger.transactions"
        surfaceflinger_transactions_config: {
            mode: MODE_CONTINUOUS
        }
    }
}

SurfaceFlinger トランザクションのトレースを生成するためのコマンド例を次に示します。

    adb shell perfetto \
    -c - --txt \
    -o /data/misc/perfetto-traces/trace \