Diese Seite wurde von der Cloud Translation API übersetzt.

Traces mit adb-Befehlen erfassen

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

Ab Android 15 sind Winscope-Traces in Perfetto integriert und werden über die Perfetto-Befehlszeile erfasst. Jeder Winscope-Trace ist eine Perfetto-Datenquelle mit einer eigenen Konfiguration. Sie können Konfigurationen einzeln oder in einer einzelnen Sitzung aktivieren.

Unter Android 14 und niedriger hat jede Winscope-Spur einen anderen Befehl und Sie können sie unabhängig voneinander erfassen. Weitere Informationen finden Sie unter Speicherung von Protokollen unter Android 14 und niedriger.

WindowManager

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

Konfigurationsoptionen

Protokollebene (log_level): Gibt die Ausführlichkeit der Protokolle an. Unterstützte Werte:
- LOG_LEVEL_VERBOSE: Alle Elemente werden mit der maximalen Anzahl von Informationen protokolliert.
- LOG_LEVEL_DEBUG: Alle Elemente werden protokolliert, aber nicht alle Konfigurationsdaten werden geschrieben.
- LOG_LEVEL_CRITICAL: Es werden nur sichtbare Elemente protokolliert, wobei der Leistungsoverhead minimal ist.
Protokollierungshäufigkeit (log_frequency): Hiermit wird festgelegt, wie oft Elemente protokolliert werden:
- LOG_FREQUENCY_FRAME: Erfasst Status-Snapshots, wenn ein Frame verbindlich wird.
- LOG_FREQUENCY_TRANSACTION: Erfasst Status-Snapshots jedes Mal, wenn eine Transaktion verbindlich wird.
- LOG_FREQUENCY_SINGLE_DUMP: Erfasst Snapshots des einzelnen Zustands, wenn die Datenquelle gestartet wird.

Weitere Informationen zu Konfigurationswerten finden Sie unter WindowManager.

Verwendungsbeispiele

Im Folgenden finden Sie ein Beispiel für den Trace-Typ „WindowManager“ 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 Protokollkonfiguration:

DEFAULT: Es werden nur die in der group_overrides angegebenen Protokollgruppen und ‑ebenen protokolliert.
ENABLE_ALL: Es werden alle Loggruppen und ‑ebenen protokolliert, sofern dies nicht in der group_overrides angegeben ist.

Minimale Logebene (default_log_from_level): Wenn diese Option festgelegt ist, werden alle Nachrichten mit einer Logebene, die höher oder gleich dieser Ebene ist, geloggt, sofern keine Gruppenüberschreibung angegeben ist. So können Sie beispielsweise alle Warnungen und Fehler protokollieren, ohne alle Protokolle 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): Hiermit können Sie die Protokollebene für jede ProtoLog-Gruppe manuell konfigurieren. Jede Gruppe enthält Folgendes:

name: Name der ProtoLog-Gruppe, die im Android-Quellcode verwendet wird.
log_from: Entspricht default_log_from_level, wird aber nur für die aktuelle Gruppe angegeben.
collect_stacktrace: Wenn dieser Parameter auf true festgelegt ist, wird der Stack-Trace für jede ProtoLog-Nachricht in der zu verfolgenden Gruppe erfasst.

Warnung :Das Logging von Stack-Traces ist langsam und wirkt sich auf die Geräteleistung aus. Diese Funktion eignet sich besser für die lokale Entwicklung.

Verwendungsbeispiele

Im Folgenden finden Sie ein Beispiel für 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 die Eingabe-Trace mit datenschutzfreundlichen Regeln gestartet oder alle Eingabeereignisse aufgezeichnet werden sollen:

TRACE_MODE_TRACE_ALL: Hier werden alle vom System verarbeiteten Eingabeereignisse aufgezeichnet, unabhängig vom Kontext, in dem sie verarbeitet wurden.
TRACE_MODE_USE_RULES: Hiermit werden die in dieser Konfiguration definierten Regeln für die Ablaufverfolgung verwendet, um anzugeben, welche Ereignisse erfasst werden sollen. Weitere Informationen zum Festlegen der Regeln für die Trace finden Sie unter android_input_event_config.proto.

Verwendungsbeispiele

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 Trace-Typ den Datenquellennamen android.surfaceflinger.layers.

Konfigurationsoptionen

Tracing-Modus (mode): Hiermit wird festgelegt, wie oft Elemente protokolliert werden:

MODE_ACTIVE: Erfasst Ebenen-Snapshots. Jedes Mal, wenn sich die Ebenen ändern, wird ein Snapshot erstellt.
MODE_GENERATED: Er generiert Layers-Snapshots aus den Transaktionen, die im internen Ringbuffer von SurfaceFlinger gespeichert werden. Die Snapshot-Generierung der Ebene erfolgt, wenn diese Datenquelle geleert wird.
MODE_DUMP: Erfasst einen Snapshot einer einzelnen Ebene.
MODE_GENERATED_BUGREPORT_ONLY: Entspricht MODE_GENERATED, löst aber die Generierung von Ebenen-Snapshots nur aus, wenn ein Fehlerbericht erstellt wird, nicht jedes Mal, wenn ein Trace gelöscht wird.

Trace-Flags (trace_flags):

TRACE_FLAG_INPUT: Wenn die Oberfläche Eingabedaten enthält, werden die Spezifikationen des Eingabefensters erfasst.
TRACE_FLAG_COMPOSITION: Der Kompositionstyp und die sichtbare Region werden nachgezeichnet.
TRACE_FLAG_EXTRA: Erfasst zusätzliche Oberflächenmetadaten, einschließlich nicht sichtbarer Ebenen.

Warnung: Dieses Feld ist sehr umfangreich und benötigt viel Arbeitsspeicher.
TRACE_FLAG_HWC: Erfasst zusätzliche unstrukturierte Metadaten des Hardware-Composers.

Warnung: Dieses Feld ist sehr umfangreich und erfordert viel Arbeitsspeicher.
TRACE_FLAG_BUFFERS: Konfiguriert SurfaceFlinger so, dass alle Pufferänderungen auf der Oberfläche erfasst werden. Standardmäßig zeichnet SurfaceFlinger nur dann einen neuen Status auf, wenn geometrische Änderungen auftreten.
TRACE_FLAG_VIRTUAL_DISPLAYS: Enthält virtuelle Anzeigeebenen im Trace.

Verwendungsbeispiele

Im Folgenden finden Sie 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 verschiedener 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 Tracetyp gibt es keine Konfigurationsoptionen.

Verwendungsbeispiele

Im folgenden Beispiel wird der Shell-Übergangs-Trace-Typ für adb verwendet:

$ 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): Hiermit wird festgelegt, wie oft 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 neuesten Transaktionen.
MODE_ACTIVE: SurfaceFlinger schreibt den Anfangsstatus und dann jede eingehende Transaktion, bis die Datenquelle angehalten wird.

Verwendungsbeispiele

Im Folgenden finden Sie 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 für diesen Trace-Typ den Namen der Datenquelle: android.inputmethod.

Konfigurationsoptionen

Für diesen Tracetyp gibt es keine Konfigurationsoptionen.

Verwendungsbeispiele

Im Folgenden finden Sie 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 für diesen Trace-Typ den Datenquellennamen android.viewcapture.

Konfigurationsoptionen

Für diesen Tracetyp gibt es keine Konfigurationsoptionen.

Verwendungsbeispiele

Im folgenden Beispiel wird der Trace-Typ „ViewCapture“ für adb verwendet:

$ 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-Protokolle 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 unter Android 14 und niedriger erfassen

Führen Sie für jede der folgenden Traces adb root aus, bevor Sie die adb shell-Befehle ausführen. Am Ende des Tracings sind die Trace-Dateien unter /data/misc/wmtrace verfügbar. Wie Sie eine Datei oder ein Verzeichnis und seine Unterverzeichnisse von einem Gerät kopieren, erfahren Sie hier.

WindowManager-Traces

So erfassen Sie WindowManager-Traces:

Trace aktivieren:
```
adb shell wm tracing start
```
Trace deaktivieren:
```
adb shell wm tracing stop
```
Protokolldaten während einer Ablaufverfolgung 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
```
Legen Sie die maximale Protokollgröße in KB fest:
```
adb shell wm tracing size
```
Trace-Status drucken:
```
adb shell wm tracing status
```
Legen Sie die Protokollebene 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 Protokollgruppen 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-Ebenen-Tracing wird die Perfetto-Spur zum Erfassen verwendet. Konfigurationsinformationen finden Sie unter Trace-Konfiguration.

Im folgenden Beispiel wird eine Konfiguration für das SurfaceFlinger-Ebenen-Tracing gezeigt:

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

Im folgenden Beispiel wird ein Befehl zum Generieren von Tracings für SurfaceFlinger-Ebenen gezeigt:

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:

So starten Sie einen Trace:

adb shell cmd window shell tracing start

Trace beenden:

adb shell cmd window shell tracing stop

So starten Sie einen Trace in der WMShell:

adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

So beenden Sie eine Trace-Datei in der WMShell:

adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

Die folgenden Befehle werden für die Eingabemethode-Eingabe (Input Method Editor, IME) verwendet:

Starten Sie die IME-Aufzeichnung für IM-Clients (Eingabemethoden), IMS (Eingabemethodendienst) und IMMS (Eingabemethodenverwaltungsdienst):
```
adb shell ime tracing start
```
Starten Sie die IME-Clients, IMS und IMMS:
```
adb shell ime tracing stop
```

SurfaceFlinger (Transaktionen)

Für die Transaktionsaufzeichnung von SurfaceFlinger wird die Perfetto-Spur verwendet. Konfigurationsinformationen finden Sie unter Trace-Konfiguration.

Im folgenden Beispiel wird eine Perfetto-Konfiguration für das aktive Tracing von SurfaceFlinger gezeigt:

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

Im folgenden Beispiel wird eine Perfetto-Konfiguration für das kontinuierliche Tracing von SurfaceFlinger gezeigt:

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

Im folgenden Beispiel wird ein Befehl zum Generieren von Tracings für SurfaceFlinger-Transaktionen gezeigt:

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