Traces mit adb-Befehlen erfassen

Sie können Winscope-Traces mit der adb-Befehlszeile in Debug-Builds (d. h. userdebug- und eng-Builds) erfassen. Führen Sie vor dem Erfassen von Winscope-Traces mit adb den Befehl adb root aus.

Ab Android 15 sind Winscope-Traces in Perfetto integriert und werden mit der Perfetto Befehlszeile erfasst. Jeder Winscope-Trace ist eine Perfetto-Datenquelle mit eigener Konfiguration. Sie können Konfigurationen einzeln oder in einer einzigen Tracing-Sitzung aktivieren.

In Android 14 und niedriger hat jeder Winscope-Trace einen anderen Befehl und Sie können jeden unabhängig erfassen. Weitere Informationen finden Sie unter Traces in Android 14 und niedriger erfassen.

WindowManager

Verwenden Sie für diesen Trace-Typ den Datenquellennamen android.windowmanager.

Konfigurationsoptionen

  • Logebene (log_level) : Gibt die Ausführlichkeit der Logs an. Unterstützte Werte:

    • LOG_LEVEL_VERBOSE: Protokolliert alle Elemente mit der maximalen Menge an Informationen.
    • LOG_LEVEL_DEBUG: Protokolliert alle Elemente, schreibt aber nicht alle Konfigurationsdaten.
    • LOG_LEVEL_CRITICAL: Protokolliert nur sichtbare Elemente mit dem geringsten Leistungsaufwand.

  • Logfrequenz (log_frequency): Definiert die Frequenz, mit der Elemente protokolliert werden:

    • LOG_FREQUENCY_FRAME: Erfasst Traces von Status-Snapshots, wenn ein Frame übernommen wird.
    • LOG_FREQUENCY_TRANSACTION: Erfasst Traces von Status-Snapshots jedes Mal, wenn eine Transaktion übernommen wird.
    • LOG_FREQUENCY_SINGLE_DUMP: Erfasst Traces von einzelnen Status-Snapshots, wenn die Datenquelle gestartet wird.

Weitere Informationen zu Konfigurationswerten finden Sie unter WindowManager.

Beispiel

Das folgende Beispiel zeigt den WindowManager-Trace-Typ für 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.windowmanager"
           windowmanager_config: {
              log_level: LOG_LEVEL_VERBOSE
              log_frequency: LOG_FREQUENCY_TRANSACTION
           }
       }
   }
EOF

ProtoLog

Verwenden Sie für diesen Trace-Typ den Datenquellennamen android.protolog.

Konfigurationsoptionen

Tracing-Modus (tracing_mode): Bestimmt die zu verwendende Logkonfiguration:

  • DEFAULT: Erfasst Traces nur von Loggruppen und -ebenen, die in den group_overrides angegeben sind.
  • ENABLE_ALL: Erfasst Traces von allen Loggruppen und -ebenen, sofern nicht in den group_overrides angegeben.

Minimale Logebene (default_log_from_level): Wenn festgelegt, wird jede Nachricht mit einer Logebene, die höher oder gleich dieser Ebene ist, erfasst, es sei denn, eine Gruppenüberschreibung ist angegeben. Dies wird beispielsweise verwendet, um alle Warnungen und Fehler zu protokollieren, ohne alle Logs aktivieren zu müssen. Folgende Werte werden unterstützt:

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

Gruppenüberschreibungen (group_overrides): Ermöglicht die manuelle Konfiguration der Logebene für jede ProtoLog-Gruppe. Jede Gruppe enthält:

  • name: Name der ProtoLog-Gruppe, verwendet im Android-Quellcode.
  • log_from: Entspricht default_log_from_level, wird aber nur für die aktuelle Gruppe angegeben.

  • collect_stacktrace: Wenn auf true gesetzt, wird der Stacktrace für jede ProtoLog-Nachricht in der Gruppe erfasst, die erfasst wird.

Beispiel

Das folgende Beispiel zeigt den ProtoLog-Trace-Typ für 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.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

Eingabe

Verwenden Sie für diesen Trace-Typ den Datenquellennamen android.input.inputevent.

Konfigurationsoptionen

Trace-Modus (trace_mode): Bestimmt, ob der Eingabe-Trace mit datenschutzfreundlichen Regeln gestartet oder alle Eingabeereignisse aufgezeichnet werden sollen:

  • TRACE_MODE_TRACE_ALL: Zeichnet alle Eingabeereignisse auf, die vom System verarbeitet werden, unabhängig vom Kontext, in dem sie verarbeitet wurden.
  • TRACE_MODE_USE_RULES: Verwendet die in dieser Konfiguration definierten Tracing-Regeln, um anzugeben, welche Ereignisse erfasst werden sollen. Weitere Informationen zum Angeben der Regeln für den Trace finden Sie unter android_input_event_config.proto.

Beispiel

Das folgende Beispiel zeigt den Eingabe-Trace-Typ für 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 (Ebenen)

Verwenden Sie für diesen Trace-Typ den Datenquellennamen android.surfaceflinger.layers.

Konfigurationsoptionen

Tracing-Modus (mode): Definiert die Frequenz, mit der Elemente protokolliert werden:

  • MODE_ACTIVE: Erfasst Traces von Ebenen-Snapshots. Jedes Mal, wenn sich Ebenen ändern, wird ein Snapshot erstellt.
  • MODE_GENERATED: Generiert Ebenen-Snapshots aus den Transaktionen, die im internen Ringpuffer von SurfaceFlinger gespeichert sind. Die Generierung von Ebenen-Snapshots erfolgt, wenn diese Datenquelle geleert wird.
  • MODE_DUMP: Erfasst Traces von einem einzelnen Ebenen-Snapshot.
  • MODE_GENERATED_BUGREPORT_ONLY: Entspricht MODE_GENERATED, löst die Generierung von Ebenen-Snapshots aber nur aus, wenn ein Fehlerbericht erstellt wird, nicht jedes Mal, wenn ein Trace geleert wird.

Trace-Flags (trace_flags):

  • TRACE_FLAG_INPUT: Wenn die Oberfläche Eingabedaten enthält, werden die Details des Eingabefensters erfasst.
  • TRACE_FLAG_COMPOSITION: Erfasst Traces des Kompositionstyps und der sichtbaren Region.

  • TRACE_FLAG_EXTRA: Erfasst Traces zusätzlicher Oberflächenmetadaten, einschließlich Offscreen-Ebenen.

  • TRACE_FLAG_HWC: Erfasst Traces zusätzlicher unstrukturierter Metadaten des Hardware-Composers.

  • TRACE_FLAG_BUFFERS: Konfiguriert SurfaceFlinger so, dass alle Pufferänderungen auf der Oberfläche erfasst werden. Standardmäßig erfasst SurfaceFlinger nur dann einen neuen Status, wenn Geometrieänderungen auftreten.

  • TRACE_FLAG_VIRTUAL_DISPLAYS: Bezieht virtuelle Anzeigeebenen in den Trace ein.

Beispiel

Das folgende Beispiel zeigt den SurfaceFlinger-Trace-Typ für 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.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

Weitere Informationen zur Bedeutung der verschiedenen Konfigurationswerte finden Sie unter SurfaceFlinger.

Shell-Übergänge

Verwenden Sie für diesen Trace-Typ den Datenquellennamen com.android.wm.shell.transition.

Konfigurationsoptionen

Für diesen Trace-Typ sind keine Konfigurationsoptionen verfügbar.

Beispiel

Das folgende Beispiel zeigt den Shell-Übergangs-Trace-Typ für 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 (Transaktionen)

Verwenden Sie für diesen Trace-Typ den Datenquellennamen android.surfaceflinger.transactions.

Konfigurationsoptionen

Tracing-Modus (mode): Definiert die Frequenz, mit der Elemente protokolliert werden:

  • MODE_CONTINUOUS: SurfaceFlinger schreibt seinen internen Ringpuffer mit Transaktionen jedes Mal, wenn die Datenquelle geleert wird. Der Ringpuffer enthält den Anfangsstatus von SurfaceFlinger und die letzten Transaktionen.

  • MODE_ACTIVE: SurfaceFlinger schreibt den Anfangsstatus und dann jede eingehende Transaktion, bis die Datenquelle beendet wird.

Beispiel

Das folgende Beispiel zeigt den SurfaceFlinger-Transaktions-Trace-Typ für 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.surfaceflinger.transactions"
           surfaceflinger_transactions_config: {
              mode: MODE_ACTIVE
           }
       }
   }
EOF

IME

Verwenden Sie für diesen Trace-Typ den Datenquellennamen android.inputmethod.

Konfigurationsoptionen

Für diesen Trace-Typ sind keine Konfigurationsoptionen verfügbar.

Beispiel

Das folgende Beispiel zeigt den IME-Trace-Typ für 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.inputmethod"
       }
   }
EOF

ViewCapture

Verwenden Sie für diesen Trace-Typ den Datenquellennamen android.viewcapture.

Konfigurationsoptionen

Für diesen Trace-Typ sind keine Konfigurationsoptionen verfügbar.

Beispiel

Das folgende Beispiel zeigt den ViewCapture-Trace-Typ für 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.viewcapture"
       }
   }
EOF

Vollständiges Beispiel

Mit Perfetto können Sie Daten aus mehreren Quellen in einer einzigen Konfiguration erfassen. Sie können alle Winscope-Traces mit einem einzigen Befehl erfassen:

$ 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

Traces in Android 14 und niedriger erfassen

Führen Sie adb root aus, bevor Sie die adb shell-Befehle für jeden der folgenden Traces ausführen. Am Ende des Traces sind die Trace-Dateien unter /data/misc/wmtrace verfügbar. Informationen zum Kopieren einer Datei oder eines Verzeichnisses und seiner Unterverzeichnisse von einem Gerät finden Sie unter Dateien auf ein Gerät und von einem Gerät kopieren.

WindowManager-Traces

So erfassen Sie WindowManager-Traces:

  • Trace aktivieren:

    adb shell wm tracing start

  • Trace deaktivieren:

    adb shell wm tracing stop

  • Protokolldaten während der Trace-Erfassung in einer Datei speichern:

    adb shell wm tracing save-for-bugreport

  • Trace einmal pro Frame protokollieren:

    adb shell wm tracing frame

  • Jede Transaktion protokollieren:

    adb shell wm tracing transaction

  • Maximale Loggröße in KB festlegen:

    adb shell wm tracing size

  • Trace-Status ausgeben:

    adb shell wm tracing status

  • Legen Sie die Logebene auf critical (nur sichtbare Fenster mit reduzierten Informationen), trim (alle Fenster mit reduzierten Informationen) oder all (alle Fenster und Informationen) fest:

    adb shell wm tracing level

WindowManager-Dumps

So erfassen Sie WindowManager-Dumps:

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

ProtoLog

Die folgenden Befehle werden für das ProtoLog System verwendet.

Im system_server-Prozess:

  • ProtoLog starten:

    adb shell cmd window logging start

  • ProtoLog beenden:

    adb shell cmd window logging stop

  • ProtoLog für bestimmte Loggruppen aktivieren:

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

  • ProtoLog für bestimmte Loggruppen deaktivieren:

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

  • Logcat-Logging für bestimmte Loggruppen aktivieren:

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

  • Logcat-Logging für bestimmte Loggruppen deaktivieren:

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

In WMShell:

  • ProtoLog starten:

    adb shell dumpsys activity service SystemUIService WMShell

SurfaceFlinger-Traces (Ebenen)

Für das Tracing von SurfaceFlinger-Ebenen wird Perfetto-Trace für die Erfassung verwendet. Konfigurationsinformationen finden Sie unter Trace-Konfiguration für Konfigurationsinformationen.

Das folgende Beispiel zeigt eine Konfiguration für das Tracing von SurfaceFlinger-Ebenen:

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
        }
    }
}

Der folgende Beispielbefehl generiert Tracing für SurfaceFlinger-Ebenen:

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

SurfaceFlinger-Dumps (Ebenen)

Führen Sie den folgenden Befehl aus, um SurfaceFlinger-Dumps zu erfassen:

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

Shell-Übergänge

Die folgenden Befehle werden für das Tracing von Übergängen verwendet.

Verwenden Sie im system_server-Prozess die folgenden Befehle:

  • Trace starten:

    adb shell cmd window shell tracing start

  • Trace beenden:

    adb shell cmd window shell tracing stop

  • Trace in WMShell starten:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • Trace in WMShell beenden:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

Die folgenden Befehle werden für das Tracing des Eingabemethoden-Editors (Input Method Editor, IME) verwendet:

  1. IME-Tracing für Eingabemethoden-Clients (Input Method, IM), Eingabemethoden-Dienste (Input Method Service, IMS) und Eingabemethoden-Verwaltungsdienste (Input Method Management Service, IMMS) starten: adb shell ime tracing start

  • Tracing von IME-Clients, IMS und IMMS starten:

    adb shell ime tracing stop

SurfaceFlinger (Transaktionen)

Für das Tracing von SurfaceFlinger-Transaktionen wird Perfetto-Trace für die Erfassung verwendet. Konfigurationsinformationen finden Sie unter Trace-Konfiguration für Konfigurationsinformationen.

Das folgende Beispiel zeigt eine Perfetto-Konfiguration für das aktive Tracing von SurfaceFlinger:

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

Das folgende Beispiel zeigt eine Perfetto-Konfiguration für das SurfaceFlinger kontinuierliche Tracing:

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
        }
    }
}

Der folgende Beispielbefehl generiert Tracing für SurfaceFlinger-Transaktionen:

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