Traces mit adb-Befehlen erfassen

Sie können Winscope-Traces mit der Befehlszeile adb in Debug-Builds (d. h. userdebug- und eng-Builds) erfassen. Bevor Sie Winscope-Traces mit adb erfassen, führen Sie adb root aus.

Ab Android 15 werden Winscope-Traces in Perfetto eingebunden und über die 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 voneinander erfassen. Weitere Informationen finden Sie unter Traces in Android 14 und niedriger aufzeichnen.

WindowManager

Verwenden Sie für diesen Tracetyp den Datenquellennamen android.windowmanager.

Konfigurationsoptionen

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

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

  • Log-Häufigkeit (log_frequency): Definiert die Häufigkeit, mit der Elemente protokolliert werden:

    • LOG_FREQUENCY_FRAME: Erfasst Status-Snapshots, wenn ein Frame übernommen wird.
    • LOG_FREQUENCY_TRANSACTION: Erstellt jedes Mal, wenn eine Transaktion übernommen wird, Snapshots des Status.
    • LOG_FREQUENCY_SINGLE_DUMP: Verfolgt einzelne Status-Snapshots, wenn die Datenquelle gestartet wird.

Weitere Informationen zu Konfigurationswerten finden Sie unter WindowManager.

Beispiel

Das folgende Beispiel zeigt den WindowManager-Tracetyp 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 Tracetyp den Datenquellennamen android.protolog.

Konfigurationsoptionen

Tracing-Modus (tracing_mode): Legt die zu verwendende Logkonfiguration fest:

  • DEFAULT: Es werden nur Loggruppen und ‑ebenen protokolliert, die in der group_overrides angegeben sind.
  • ENABLE_ALL: Alle Loggruppen und ‑ebenen werden verfolgt, sofern nicht in group_overrides angegeben.

Geringste Logebene (default_log_from_level): Wenn diese Option festgelegt ist, wird jede Nachricht mit einer Logebene, die höher als oder gleich dieser Ebene ist, protokolliert, sofern keine Gruppenüberschreibung angegeben ist. So können beispielsweise alle Warnungen und Fehler protokolliert werden, ohne dass alle Logs aktiviert werden 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 des Protokollierungsgrads für jede ProtoLog-Gruppe. Jede Gruppe enthält:

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

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

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 Tracetyp den Datenquellennamen android.input.inputevent.

Konfigurationsoptionen

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

  • TRACE_MODE_TRACE_ALL: Erfasst alle vom System verarbeiteten Eingabeereignisse, unabhängig vom Kontext, in dem sie verarbeitet wurden.
  • TRACE_MODE_USE_RULES: Gibt an, welche Ereignisse aufgezeichnet werden sollen. Dazu werden die in dieser Konfiguration definierten Tracing-Regeln verwendet. Weitere Informationen zum Angeben der Regeln für den Trace finden Sie unter android_input_event_config.proto.

Beispiel

Im Folgenden finden Sie ein Beispiel für 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 Tracetyp den Datenquellennamen android.surfaceflinger.layers.

Konfigurationsoptionen

Tracing-Modus (mode): Definiert die Häufigkeit, mit der Elemente protokolliert werden:

  • MODE_ACTIVE: Snapshots von Traces-Layern. Jedes Mal, wenn sich eine Ebene ändert, wird ein Snapshot erstellt.
  • MODE_GENERATED: Generiert Ebenen-Snapshots aus den Transaktionen, die im internen Ringpuffer von SurfaceFlinger gespeichert sind. Die Momentaufnahmen der Ebene werden erstellt, wenn diese Datenquelle geleert wird.
  • MODE_DUMP: Erstellt einen Snapshot einer einzelnen Ebene.
  • MODE_GENERATED_BUGREPORT_ONLY: Wie MODE_GENERATED, löst die Generierung von Ebenen-Snapshots jedoch nur dann 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: Verfolgt den Kompositionstyp und die sichtbare Region.

  • TRACE_FLAG_EXTRA: Erfasst zusätzliche Metadaten für Oberflächen, einschließlich Offscreen-Layern.

  • TRACE_FLAG_HWC: Zeichnet zusätzliche unstrukturierte Metadaten des Hardware-Composers auf.

  • TRACE_FLAG_BUFFERS: Konfiguriert SurfaceFlinger so, dass alle Pufferänderungen auf der Oberfläche verfolgt werden. Standardmäßig zeichnet SurfaceFlinger einen neuen Status nur auf, wenn sich die Geometrie ändert.

  • TRACE_FLAG_VIRTUAL_DISPLAYS: Enthält virtuelle Displayebenen im Trace.

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 Tracetyp den Datenquellennamen com.android.wm.shell.transition.

Konfigurationsoptionen

Für diesen Tracetyp gibt es keine Konfigurationsoptionen.

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 Tracetyp den Datenquellennamen android.surfaceflinger.transactions.

Konfigurationsoptionen

Tracing-Modus (mode): Definiert die Häufigkeit, 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 ursprünglichen Status von SurfaceFlinger und die letzten Transaktionen.

  • MODE_ACTIVE: SurfaceFlinger schreibt den ursprünglichen Zustand und dann jede eingehende Transaktion, bis die Datenquelle beendet wird.

Beispiel

Das folgende Beispiel zeigt den Trace-Typ „SurfaceFlinger-Transaktionen“ 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 Tracetyp den Datenquellennamen android.inputmethod.

Konfigurationsoptionen

Für diesen Tracetyp gibt es keine Konfigurationsoptionen.

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 Tracetyp den Datenquellennamen android.viewcapture.

Konfigurationsoptionen

Für diesen Tracetyp gibt es keine Konfigurationsoptionen.

Beispiel

Das folgende Beispiel zeigt den Trace-Typ „ViewCapture“ 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. Mit einem einzigen Befehl können Sie alle Winscope-Traces 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 aufzeichnen

Führen Sie adb root aus, bevor Sie die adb shell-Befehle für die einzelnen der folgenden Traces ausführen. Am Ende des Traces sind die Trace-Dateien in /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 Aufzeichnung eines Traces 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 Protokollgröße (in KB) festlegen:

    adb shell wm tracing size

  • Status des Druck-Traces:

    adb shell wm tracing status

  • Legen Sie die Protokollebene auf critical (nur 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...]

  • Aktivieren Sie das Logcat-Logging für bestimmte Loggruppen:

    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 SurfaceFlinger-Layer-Tracing wird Perfetto-Trace zum Erfassen verwendet. Konfigurationsinformationen finden Sie unter Trace-Konfiguration.

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

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

Mit dem folgenden Beispielbefehl wird das Tracing für SurfaceFlinger-Ebenen generiert:

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 die Übergangsverfolgung 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

  • Starten Sie einen Trace in WMShell:

    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 IME-Tracing (Input Method Editor) verwendet:

  1. Starten Sie das IME-Tracing für IM-Clients (Input Method), IMS (Input Method Service) und IMMS (Input Method Management Service): adb shell ime tracing start

  • IME-Clients, IMS und IMMS verfolgen:

    adb shell ime tracing stop

SurfaceFlinger (Transaktionen)

Für das SurfaceFlinger-Transaktions-Tracing wird der Perfetto-Trace zum Erfassen verwendet. Konfigurationsinformationen finden Sie unter Trace-Konfiguration.

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

Mit dem folgenden Beispielbefehl wird das Tracing für SurfaceFlinger-Transaktionen generiert:

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