Acquisisci le tracce con i comandi adb

Le tracce di Winscope possono essere raccolte con la riga di comando adb nelle build di debug (ovvero le build userdebug e eng). Prima di raccogliere le tracce 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 Perfetto. Ogni traccia Winscope è un'origine dati Perfetto con la propria configurazione. Puoi attivare le configurazioni singolarmente o in una singola sessione di monitoraggio.

In Android 14 e versioni precedenti, ogni traccia Winscope ha un comando diverso e puoi raccoglierle ciascuna in modo indipendente. 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 modalità di dettaglio dei log. Valori supportati:

    • LOG_LEVEL_VERBOSE: registra tutti gli elementi con la quantità massima 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 il minimo ovverhead 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: acquisisce snapshot dello stato delle tracce ogni volta che viene eseguita la commit di una transazione.
    • LOG_FREQUENCY_SINGLE_DUMP: esegue il monitoraggio di singoli snapshot dello stato quando viene avviata la fonte di dati.

Per informazioni dettagliate sui valori di configurazione, consulta WindowManager.

Esempio

Di seguito è riportato un esempio del tipo di traccia 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 monitoraggio (tracing_mode): determina la configurazione del log da utilizzare:

  • DEFAULT: vengono tracciati 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 sia specificato in group_overrides.

Livello minimo del log (default_log_from_level): se impostato, qualsiasi messaggio con un livello del log superiore o uguale a questo livello viene sottoposto a tracciamento, a meno che non sia specificata un'override di gruppo. Ad esempio, viene utilizzato per attivare la registrazione di tutti gli avvisi e gli errori, senza dover attivare 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

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

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

  • collect_stacktrace: se impostato su true, raccoglie la traccia dello stack per ogni messaggio ProtoLog nel gruppo sottoposto a tracciatura.

Esempio

Di seguito è riportato un esempio del tipo di traccia 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 traccia (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 tracciatura definite in questo file di configurazione per specificare gli eventi da tracciare. Per ulteriori informazioni su come specificare le regole per la traccia, consulta android_input_event_config.proto.

Esempio

Di seguito è riportato un esempio di 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 monitoraggio (mode): definisce la frequenza con cui vengono registrati gli elementi:

  • MODE_ACTIVE: traccia gli snapshot dei livelli. Viene acquisita un'istantanea ogni volta che si verifica una variazione dei livelli.
  • MODE_GENERATED: genera snapshot dei livelli dalle transazioni memorizzate nel buffer circolare interno di SurfaceFlinger. La generazione degli istantanei del livello avviene quando viene svuotata questa origine dati.
  • MODE_DUMP: traccia uno snapshot di un singolo livello.
  • MODE_GENERATED_BUGREPORT_ONLY: come MODE_GENERATED, ma attiva la generazione di istantanee dei livelli solo quando viene generato un report di bug, non ogni volta che viene svuotata una traccia.

Flag di traccia (trace_flags):

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

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

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

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

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

Esempio

Di seguito è riportato un esempio del tipo di traccia 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 informazioni dettagliate 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

Di seguito è riportato un esempio del 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 monitoraggio (mode): definisce la frequenza con cui vengono registrati gli elementi:

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

  • MODE_ACTIVE: SurfaceFlinger scrive lo stato iniziale e poi ogni transazione in entrata fino all'arresto dell'origine dati.

Esempio

Di seguito è riportato un esempio del 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

Di seguito è riportato un esempio di 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

Di seguito è riportato un esempio del tipo di traccia 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 i dati da più origini in un'unica configurazione. Puoi raccogliere tutte le tracce Winscope con un solo 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 su e da un dispositivo.

Tracce WindowManager

Per acquisire le tracce di WindowManager:

  • Attiva la traccia:

    adb shell wm tracing start

  • Per disattivare la traccia:

    adb shell wm tracing stop

  • Salva i dati di log in un 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 le dimensioni massime del log (in KB):

    adb shell wm tracing size

  • Stampa stato 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.

Nella procedura system_server:

  • Avvia ProtoLog:

    adb shell cmd window logging start

  • Interrompi ProtoLog:

    adb shell cmd window logging stop

  • Attiva ProtoLog per determinati gruppi di log:

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

  • Disattiva ProtoLog per determinati gruppi di log:

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

  • Attiva il logging di Logcat per determinati gruppi di log:

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

  • Disattiva il logging di Logcat per determinati gruppi di log:

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

In WMShell:

  • Avvia ProtoLog:

    adb shell dumpsys activity service SystemUIService WMShell

Tracce (livelli) di SurfaceFlinger

Il monitoraggio del livello SurfaceFlinger utilizza la traccia Perfetto per l'acquisizione. Per informazioni sulla configurazione, consulta Configurazione dei traccianti.

Consulta il seguente esempio di configurazione per il monitoraggio del livello 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
        }
    }
}

Consulta il seguente comando di esempio per generare il monitoraggio per i livelli SurfaceFlinger:

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

Dump di SurfaceFlinger (livelli)

Per acquisire i dump di SurfaceFlinger:

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

Transizioni della shell

I seguenti comandi vengono utilizzati per il monitoraggio delle transizioni.

Nella procedura system_server:

  • Avvia una traccia:

    adb shell cmd window shell tracing start

  • Interrompere una traccia:

    adb shell cmd window shell tracing stop

  • Avvia una traccia in WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • Interrompi una traccia in WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

I seguenti comandi vengono utilizzati per il monitoraggio dell'editor di metodi di inserimento (IME):

  • Avvia il monitoraggio IME per i client di metodo di inserimento (IM), il servizio di metodo di inserimento (IMS) e il servizio di gestione del metodo di inserimento (IMMS):

    adb shell ime tracing start

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

    adb shell ime tracing stop

SurfaceFlinger (transazioni)

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

Guarda il seguente esempio di configurazione di Perfetto per il monitoraggio attivo di 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

Consulta il seguente esempio di configurazione di Perfetto per il monitoraggio 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
        }
    }
}

Consulta il seguente comando di esempio per generare il monitoraggio per le transazioni di SurfaceFlinger:

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