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 を使用すると、1 つの構成で複数のソースからデータを収集できます。すべての 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 \