Acquisisci le tracce con i comandi adb

Puoi raccogliere le tracce di Winscope utilizzando la riga di comando adb nelle build di debug (ovvero le build userdebug e eng). Prima di raccogliere le tracce di Winscope con adb, esegui adb root.

A partire da Android 15, le tracce di Winscope sono integrate in Perfetto e vengono raccolte utilizzando la riga di comando di Perfetto. Ogni traccia di Winscope è un'origine dati di Perfetto con una propria configurazione. Puoi abilitare le configurazioni singolarmente o in una singola sessione di tracciamento.

In Android 14 e versioni precedenti, ogni traccia di Winscope ha un comando diverso e puoi raccoglierle singolarmente. Per ulteriori informazioni, consulta Acquisire tracce in Android 14 e versioni precedenti.

WindowManager

Utilizza il nome dell'origine dati android.windowmanager per questo tipo di traccia.

Opzioni di configurazione

  • Livello di log (log_level): specifica la verbosità dei log. Valori supportati:

    • LOG_LEVEL_VERBOSE: registra tutti gli elementi con la massima quantità di informazioni.
    • LOG_LEVEL_DEBUG: registra tutti gli elementi, ma non scrive tutti i dati di configurazione.
    • LOG_LEVEL_CRITICAL: registra solo gli elementi visibili, con la quantità minima di overhead delle prestazioni.

  • Frequenza dei log (log_frequency): definisce la frequenza con cui vengono registrati gli elementi:

    • LOG_FREQUENCY_FRAME: traccia gli snapshot dello stato quando viene eseguito il commit di un frame.
    • LOG_FREQUENCY_TRANSACTION: traccia gli snapshot dello stato ogni volta che viene eseguito il commit di una transazione.
    • LOG_FREQUENCY_SINGLE_DUMP: traccia i singoli snapshot dello stato all'avvio dell'origine dati.

Per i dettagli sui valori di configurazione, consulta WindowManager.

Esempio

L'esempio seguente mostra il tipo di traccia di WindowManager per 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

Utilizza il nome dell'origine dati android.protolog per questo tipo di traccia.

Opzioni di configurazione

Modalità di tracciamento (tracing_mode): determina la configurazione dei log da utilizzare:

  • DEFAULT: traccia solo i gruppi e i livelli di log specificati in group_overrides.
  • ENABLE_ALL: traccia tutti i gruppi e i livelli di log, a meno che non siano specificati in group_overrides.

Livello di log minimo (default_log_from_level): se impostato, viene tracciato qualsiasi messaggio con un livello di log superiore o uguale a questo livello, a meno che non sia specificata una sostituzione del gruppo. Ad esempio, viene utilizzato per abilitare la registrazione di tutti gli avvisi e gli errori, senza dover abilitare tutti i log. I valori supportati sono:

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

Sostituzioni di gruppo (group_overrides): consente la configurazione manuale del livello di log per ogni gruppo ProtoLog. Ogni gruppo contiene:

  • name: nome del gruppo ProtoLog, utilizzato nel codice sorgente di Android.
  • log_from: uguale a default_log_from_level, ma specificato solo per il gruppo corrente.

  • collect_stacktrace: se impostato su true, raccoglie l'analisi dello stack per ogni messaggio ProtoLog nel gruppo tracciato.

Esempio

L'esempio seguente mostra il tipo di traccia di ProtoLog per 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

Input

Utilizza il nome dell'origine dati android.input.inputevent per questo tipo di traccia.

Opzioni di configurazione

Modalità di tracciamento (trace_mode): determina se la traccia di input deve essere avviata utilizzando regole che tutelano la privacy o registrare tutti gli eventi di input:

  • TRACE_MODE_TRACE_ALL: registra tutti gli eventi di input elaborati dal sistema, indipendentemente dal contesto in cui sono stati elaborati.
  • TRACE_MODE_USE_RULES: utilizza le regole di tracciamento definite in questa configurazione per specificare gli eventi da tracciare. Per ulteriori informazioni sulla specifica delle regole per la traccia, consulta android_input_event_config.proto.

Esempio

Di seguito è riportato un esempio del tipo di traccia di input per 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 (livelli)

Utilizza il nome dell'origine dati android.surfaceflinger.layers per questo tipo di traccia.

Opzioni di configurazione

Modalità di tracciamento (mode): definisce la frequenza con cui vengono registrati gli elementi:

  • MODE_ACTIVE: traccia gli snapshot dei livelli. Viene eseguito uno snapshot ogni volta che si verifica una modifica dei livelli.
  • MODE_GENERATED: genera snapshot dei livelli dalle transazioni mantenute nel buffer circolare interno di SurfaceFlinger. La generazione degli snapshot del livello si verifica quando viene scaricata questa origine dati.
  • MODE_DUMP: traccia un singolo snapshot dei livelli.
  • MODE_GENERATED_BUGREPORT_ONLY: uguale a MODE_GENERATED, ma attiva la generazione degli snapshot dei livelli solo quando viene creato un report sui bug, non ogni volta che viene scaricata una traccia.

Flag di traccia (trace_flags):

  • TRACE_FLAG_INPUT: se la superficie contiene dati di input, tiene traccia delle specifiche della finestra di input.
  • TRACE_FLAG_COMPOSITION: traccia il tipo di composizione e la regione visibile.

  • TRACE_FLAG_EXTRA: traccia i metadati aggiuntivi della superficie, inclusi i livelli fuori schermo.

  • TRACE_FLAG_HWC: traccia i metadati aggiuntivi non strutturati del compositore hardware.

  • TRACE_FLAG_BUFFERS: configura SurfaceFlinger per tracciare tutte le modifiche del buffer sulla superficie. Per impostazione predefinita, SurfaceFlinger traccia un nuovo stato solo quando si verificano modifiche alla geometria.

  • TRACE_FLAG_VIRTUAL_DISPLAYS: include i livelli di visualizzazione virtuale nella traccia.

Esempio

L'esempio seguente mostra il tipo di traccia di SurfaceFlinger per 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

Per i dettagli sul significato dei diversi valori di configurazione, consulta SurfaceFlinger.

Transizioni della shell

Utilizza il nome dell'origine dati com.android.wm.shell.transition per questo tipo di traccia.

Opzioni di configurazione

Questo tipo di traccia non ha opzioni di configurazione.

Esempio

L'esempio seguente mostra il tipo di traccia di transizione della shell per 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 (transazioni)

Utilizza il nome dell'origine dati android.surfaceflinger.transactions per questo tipo di traccia.

Opzioni di configurazione

Modalità di tracciamento (mode): definisce la frequenza con cui vengono registrati gli elementi:

  • MODE_CONTINUOUS: SurfaceFlinger scrive il buffer circolare interno delle transazioni ogni volta che viene scaricata l'origine dati. Il buffer circolare contiene lo stato iniziale di SurfaceFlinger e le transazioni più recenti.

  • MODE_ACTIVE: SurfaceFlinger scrive lo stato iniziale e poi ogni transazione in entrata finché l'origine dati non viene arrestata.

Esempio

L'esempio seguente mostra il tipo di traccia delle transazioni di SurfaceFlinger per 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

Utilizza il nome dell'origine dati android.inputmethod per questo tipo di traccia.

Opzioni di configurazione

Questo tipo di traccia non ha opzioni di configurazione.

Esempio

L'esempio seguente mostra il tipo di traccia IME per 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

Utilizza il nome dell'origine dati android.viewcapture per questo tipo di traccia.

Opzioni di configurazione

Questo tipo di traccia non ha opzioni di configurazione.

Esempio

L'esempio seguente mostra il tipo di traccia di ViewCapture per 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

Esempio completo

Perfetto ti consente di raccogliere dati da più origini in un'unica configurazione. Puoi raccogliere tutte le tracce di Winscope utilizzando un singolo comando:

$ 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

Acquisire tracce in Android 14 e versioni precedenti

Esegui adb root prima di eseguire i comandi adb shell per ciascuna delle seguenti tracce. Al termine della traccia, i file di traccia sono disponibili in /data/misc/wmtrace. Per copiare un file o una directory e le relative sottodirectory da un dispositivo, consulta Copiare file da e verso un dispositivo.

Tracce di WindowManager

Per acquisire le tracce di WindowManager:

  • Abilita la traccia:

    adb shell wm tracing start

  • Disabilita la traccia:

    adb shell wm tracing stop

  • Salva i dati di logging nel file durante l'esecuzione di un'acquisizione della traccia:

    adb shell wm tracing save-for-bugreport

  • Registra la traccia una volta per frame:

    adb shell wm tracing frame

  • Registra ogni transazione:

    adb shell wm tracing transaction

  • Imposta la dimensione massima dei log (in kB):

    adb shell wm tracing size

  • Stampa lo stato della traccia:

    adb shell wm tracing status

  • Imposta il livello di log su critical (solo finestre visibili con informazioni ridotte), trim (tutte le finestre con informazioni ridotte) o all (tutte le finestre e le informazioni):

    adb shell wm tracing level

Dump di WindowManager

Per acquisire i dump di WindowManager:

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

ProtoLog

I seguenti comandi vengono utilizzati per il sistema ProtoLog.

Nel processo system_server:

  • Avvia ProtoLog:

    adb shell cmd window logging start

  • Arresta ProtoLog:

    adb shell cmd window logging stop

  • Abilita ProtoLog per i gruppi di log specificati:

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

  • Disabilita ProtoLog per i gruppi di log specificati:

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

  • Abilita la registrazione di Logcat per i gruppi di log specificati:

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

  • Disabilita la registrazione di Logcat per i gruppi di log specificati:

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

In WMShell:

  • Avvia ProtoLog:

    adb shell dumpsys activity service SystemUIService WMShell

Tracce di SurfaceFlinger (livelli)

Il tracciamento dei livelli di SurfaceFlinger utilizza la traccia di Perfetto per l'acquisizione. Per informazioni sulla configurazione, consulta Configurazione della traccia.

L'esempio seguente mostra una configurazione per il tracciamento dei livelli di 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
        }
    }
}

Il seguente comando di esempio genera il tracciamento per i livelli di SurfaceFlinger:

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

Dump di SurfaceFlinger (livelli)

Per acquisire i dump di SurfaceFlinger, esegui il seguente comando:

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

Transizioni della shell

I seguenti comandi vengono utilizzati per il tracciamento delle transizioni.

Nel processo system_server, utilizza i seguenti comandi:

  • Avvia una traccia:

    adb shell cmd window shell tracing start

  • Arresta una traccia:

    adb shell cmd window shell tracing stop

  • Avvia una traccia in WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • Arresta una traccia in WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

I seguenti comandi vengono utilizzati per il tracciamento di Input Method Editor (IME):

  1. Avvia il tracciamento IME per i client di Input Method (IM), Input Method Service (IMS) e Input Method Management Service (IMMS): adb shell ime tracing start

  • Avvia il tracciamento dei client IME, IMS e IMMS:

    adb shell ime tracing stop

SurfaceFlinger (transazioni)

Il tracciamento delle transazioni di SurfaceFlinger utilizza la traccia di Perfetto per l'acquisizione. Per informazioni sulla configurazione, consulta Configurazione della traccia.

L'esempio seguente mostra una configurazione di Perfetto per il SurfaceFlinger tracciamento attivo:

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

L'esempio seguente mostra una configurazione di Perfetto per il tracciamento continuo di 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
        }
    }
}

Il seguente comando di esempio genera il tracciamento per le transazioni di SurfaceFlinger:

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