Acquisisci le tracce con i comandi adb

Le tracce 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 di Perfetto. Ogni traccia Winscope è un'origine dati Perfetto con una propria configurazione. Puoi attivare le configurazioni singolarmente o in un'unica sessione di tracciamento.

In Android 14 e versioni precedenti, ogni traccia Winscope ha un comando diverso e puoi raccoglierle separatamente. Per saperne di più, consulta la sezione 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 il livello di dettaglio del 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 il minimo overhead delle prestazioni.

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

    • 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 gli snapshot di un singolo stato all'avvio dell'origine dati.

Per maggiori dettagli sui valori di configurazione, vedi 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 tracciamento (tracing_mode): determina la configurazione dei log da utilizzare:

  • DEFAULT: Traccia solo i gruppi di log e i livelli 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 monitorato qualsiasi messaggio con un livello di log superiore o uguale a questo livello, a meno che non venga specificato un override del gruppo. Ad esempio, viene utilizzato per consentire 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

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

  • name: il 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 lo stack trace per ogni messaggio ProtoLog nel gruppo di cui viene eseguita la traccia.

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à 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 tracciamento definite in questa 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 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: Snapshot dei livelli di traccia. Viene scattata un'istantanea ogni volta che si verifica una modifica dei livelli.
  • MODE_GENERATED: genera snapshot dei livelli dalle transazioni conservate nel buffer circolare interno di SurfaceFlinger. La generazione degli snapshot del livello si verifica quando questa origine dati viene svuotata.
  • MODE_DUMP: Traccia uno snapshot di un singolo livello.
  • MODE_GENERATED_BUGREPORT_ONLY: come MODE_GENERATED, ma attiva la generazione di snapshot dei livelli solo quando viene creato un report bug, non ogni volta che viene svuotata una traccia.

Flag di traccia (trace_flags):

  • TRACE_FLAG_INPUT: se la superficie contiene dati di input, tiene traccia dei dettagli 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 metadati aggiuntivi non strutturati del compositore hardware.

  • TRACE_FLAG_BUFFERS: configura SurfaceFlinger per tracciare tutte le modifiche al 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 della 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 l'origine dati viene svuotata. 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

Di seguito è riportato un esempio del tipo di traccia delle transazioni 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 del 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 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 da e verso un dispositivo.

Tracce di WindowManager

Per acquisire le tracce di WindowManager:

  • Abilita traccia:

    adb shell wm tracing start

  • Disattivare 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 del log (in KB):

    adb shell wm tracing size

  • Stato della traccia di stampa:

    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 di system_server:

  • Avvia ProtoLog:

    adb shell cmd window logging start

  • Stop 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...]

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

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

  • Disattiva la registrazione 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 SurfaceFlinger utilizza la traccia Perfetto per l'acquisizione. Per informazioni sulla configurazione, vedi Configurazione della traccia.

Vedi il seguente esempio di configurazione per la traccia dei livelli 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 la traccia dei 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 tracciamento delle transizioni.

Nel processo di 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

  • Arresta una traccia in WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

I seguenti comandi vengono utilizzati per la tracciatura dell'Input Method Editor (IME):

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

    adb shell ime tracing start

  • Inizia a tracciare i client IME, IMS e IMMS:

    adb shell ime tracing stop

SurfaceFlinger (transazioni)

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

Di seguito è riportato un esempio di configurazione di Perfetto per la traccia attiva 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

Di seguito è riportato un esempio di configurazione di Perfetto per la traccia continua 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 la traccia delle transazioni di SurfaceFlinger:

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