Ab dem 27. März 2025 empfehlen wir, android-latest-release anstelle von aosp-main zu verwenden, um AOSP zu erstellen und Beiträge dazu zu leisten. Weitere Informationen finden Sie unter Änderungen am AOSP.

Diese Seite wurde von der Cloud Translation API übersetzt.

Traces mit adb-Befehlen erfassen

Winscope-Traces können mit der Befehlszeile adb in Debug-Builds (d. h. userdebug- und eng-Builds) erfasst werden. 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 ist ein Beispiel für 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.

Warnung :Das Protokollieren von Stacktraces ist langsam und beeinträchtigt die Geräteleistung. Diese Funktion eignet sich besser für die lokale Entwicklung.

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.

Warnung :Dieses Feld ist sehr ausführlich und erfordert viel Speicherplatz.
TRACE_FLAG_HWC: Zeichnet zusätzliche unstrukturierte Metadaten des Hardware-Composers auf.

Warnung :Dieses Feld ist sehr ausführlich und erfordert viel Arbeitsspeicher.
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

Hier ist ein Beispiel für 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

Hier ist ein Beispiel für den Shell-Übergangstrace-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 Zustand 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 ist ein Beispiel für 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 den Datenquellennamen: android.inputmethod für diesen Tracetyp.

Konfigurationsoptionen

Für diesen Tracetyp gibt es keine Konfigurationsoptionen.

Beispiel

Hier ein Beispiel für 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 den Datenquellennamen android.viewcapture für diesen Tracetyp.

Konfigurationsoptionen

Für diesen Tracetyp gibt es keine Konfigurationsoptionen.

Beispiel

Das Folgende ist ein Beispiel für den ViewCapture-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.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 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.

Hier sehen Sie ein Beispiel für 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
        }
    }
}

Hier ist ein Beispielbefehl zum Generieren von Tracing-Daten für SurfaceFlinger-Ebenen:

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

SurfaceFlinger-Dumps (Ebenen)

So erfassen Sie SurfaceFlinger-Dumps:

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

Shell-Übergänge

Die folgenden Befehle werden für die Übergangsverfolgung verwendet.

Im system_server-Prozess:

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:

IME-Tracing für IM-Clients (Input Method), IMS (Input Method Service) und IMMS (Input Method Management Service) starten:
```
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.

Hier ist ein Beispiel für 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

Hier ist ein Beispiel für eine Perfetto-Konfiguration für das kontinuierliche Tracing von SurfaceFlinger:

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

Hier ist ein Beispiel für einen Befehl zum Generieren von Tracing-Daten für SurfaceFlinger-Transaktionen:

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

Traces mit adb-Befehlen erfassen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

WindowManager

Konfigurationsoptionen

Beispiel

ProtoLog

Konfigurationsoptionen

Beispiel

Eingabe

Konfigurationsoptionen

Beispiel

SurfaceFlinger (Ebenen)

Konfigurationsoptionen

Beispiel

Shell-Übergänge

Konfigurationsoptionen

Beispiel

SurfaceFlinger (Transaktionen)

Konfigurationsoptionen

Beispiel

IME

Konfigurationsoptionen

Beispiel

ViewCapture

Konfigurationsoptionen

Beispiel

Vollständiges Beispiel

Traces in Android 14 und niedriger aufzeichnen

WindowManager-Traces

WindowManager-Dumps

ProtoLog

SurfaceFlinger-Traces (Ebenen)

SurfaceFlinger-Dumps (Ebenen)

Shell-Übergänge

IME

SurfaceFlinger (Transaktionen)

Traces mit adb-Befehlen erfassen