Capturar rastros com comandos adb

É possível coletar rastros do Winscope usando a linha de comando adb em builds de depuração (ou seja, builds userdebug e eng). Antes de coletar rastros do Winscope com adb, execute adb root.

A partir do Android 15, os rastros do Winscope são integrados ao Perfetto e coletados usando a linha de comando do Perfetto. Cada rastro do Winscope é uma fonte de dados do Perfetto com a própria configuração. É possível ativar as configurações individualmente ou em uma única sessão de rastreamento.

No Android 14 e versões anteriores, cada rastro do Winscope tem um comando diferente, e é possível coletar cada um de forma independente. Consulte Capturar rastros no Android 14 e versões anteriores para mais informações.

WindowManager

Use o nome da fonte de dados android.windowmanager para esse tipo de rastro.

Opções de configuração

  • Nível de registro (log_level) : especifica a verbosidade do registro. Valores compatíveis:

    • LOG_LEVEL_VERBOSE: registra todos os elementos com a quantidade máxima de informações.
    • LOG_LEVEL_DEBUG: registra todos os elementos, mas não grava todos os dados de configuração.
    • LOG_LEVEL_CRITICAL: registra apenas elementos visíveis, com a quantidade mínima de sobrecarga de desempenho.

  • Frequência de registro (log_frequency): define a frequência com que os itens são registrados:

    • LOG_FREQUENCY_FRAME: rastreia snapshots de estado quando um frame é confirmado.
    • LOG_FREQUENCY_TRANSACTION: rastreia snapshots de estado sempre que uma transação é confirmada.
    • LOG_FREQUENCY_SINGLE_DUMP: rastreia snapshots de estado único quando a fonte de dados é iniciada.

Consulte WindowManager para detalhes sobre os valores de configuração.

Exemplo

O exemplo a seguir mostra o tipo de rastro do WindowManager para 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

Use o nome da fonte de dados android.protolog para esse tipo de rastro.

Opções de configuração

Modo de rastreamento (tracing_mode): determina a configuração de registro a ser usada:

  • DEFAULT: rastreia apenas grupos e níveis de registro especificados em group_overrides.
  • ENABLE_ALL: rastreia todos os grupos e níveis de registro, a menos que especificado em group_overrides.

Nível mínimo de registro (default_log_from_level): quando definido, qualquer mensagem com um nível de registro maior ou igual a esse nível é rastreada, a menos que uma substituição de grupo seja especificada. Por exemplo, isso é usado para ativar todos os avisos e erros a serem registrados, sem precisar ativar todos os registros. Os valores compatíveis são:

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

Substituições de grupo (group_overrides): permite a configuração manual do nível de registro para cada grupo ProtoLog. Cada grupo contém:

  • name: nome do grupo ProtoLog, usado no código-fonte do Android.
  • log_from: igual a default_log_from_level, mas especificado apenas para o grupo atual.

  • collect_stacktrace: quando definido como true, coleta o stack trace de cada mensagem ProtoLog no grupo que está sendo rastreado.

Exemplo

O exemplo a seguir mostra o tipo de rastro do ProtoLog para 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

Entrada

Use o nome da fonte de dados android.input.inputevent para esse tipo de rastro.

Opções de configuração

Modo de rastro (trace_mode): determina se o rastro de entrada precisa ser iniciado usando regras que preservam a privacidade ou registrar todos os eventos de entrada:

  • TRACE_MODE_TRACE_ALL: registra todos os eventos de entrada processados pelo sistema, independentemente do contexto em que foram processados.
  • TRACE_MODE_USE_RULES: usa as regras de rastreamento definidas nessa configuração para especificar quais eventos rastrear. Consulte android_input_event_config.proto para mais informações sobre como especificar as regras do rastro.

Exemplo

Confira a seguir um exemplo do tipo de rastro de entrada para 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 (camadas)

Use o nome da fonte de dados android.surfaceflinger.layers para esse tipo de rastro.

Opções de configuração

Modo de rastreamento (mode): define a frequência com que os itens são registrados:

  • MODE_ACTIVE: rastreia snapshots de camadas. Um snapshot é feito sempre que ocorre uma mudança de camadas.
  • MODE_GENERATED: gera snapshots de camadas das transações mantidas no buffer de anel interno do SurfaceFlinger. A geração de snapshots da camada ocorre quando essa fonte de dados é liberada.
  • MODE_DUMP: rastreia um único snapshot de camadas.
  • MODE_GENERATED_BUGREPORT_ONLY: igual a MODE_GENERATED, mas aciona a geração de snapshots de camadas apenas quando um relatório de bugs é feito, não sempre que um rastro é liberado.

Flags de rastro (trace_flags):

  • TRACE_FLAG_INPUT: se a superfície contiver dados de entrada, rastreia os detalhes da janela de entrada.
  • TRACE_FLAG_COMPOSITION: rastreia o tipo de composição e a região visível.

  • TRACE_FLAG_EXTRA: rastreia metadados de superfície adicionais, incluindo camadas fora da tela.

  • TRACE_FLAG_HWC: rastreia metadados adicionais não estruturados do compositor de hardware.

  • TRACE_FLAG_BUFFERS: configura o SurfaceFlinger para rastrear todas as mudanças de buffer na superfície. Por padrão, o SurfaceFlinger rastreia um novo estado apenas quando ocorrem alterações de geometria.

  • TRACE_FLAG_VIRTUAL_DISPLAYS: inclui camadas de exibição virtual no rastro.

Exemplo

O exemplo a seguir mostra o tipo de rastro do SurfaceFlinger para 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

Consulte SurfaceFlinger para detalhes sobre o significado de diferentes valores de configuração.

Transições de shell

Use o nome da fonte de dados com.android.wm.shell.transition para esse tipo de rastro.

Opções de configuração

Esse tipo de rastro não tem opções de configuração.

Exemplo

O exemplo a seguir mostra o tipo de rastro de transição de shell para 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 (transações)

Use o nome da fonte de dados android.surfaceflinger.transactions para esse tipo de rastro.

Opções de configuração

Modo de rastreamento (mode): define a frequência com que os itens são registrados:

  • MODE_CONTINUOUS: o SurfaceFlinger grava o buffer de anel interno de transações sempre que a fonte de dados é liberada. O buffer de anel contém o estado inicial do SurfaceFlinger e as transações mais recentes.

  • MODE_ACTIVE: o SurfaceFlinger grava o estado inicial e, em seguida, cada transação recebida até que a fonte de dados seja interrompida.

Exemplo

O exemplo a seguir mostra o tipo de rastro de transações do SurfaceFlinger para 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

Use o nome da fonte de dados android.inputmethod para esse tipo de rastro.

Opções de configuração

Esse tipo de rastro não tem opções de configuração.

Exemplo

O exemplo a seguir mostra o tipo de rastro do IME para 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

Use o nome da fonte de dados android.viewcapture para esse tipo de rastro.

Opções de configuração

Esse tipo de rastro não tem opções de configuração.

Exemplo

O exemplo a seguir mostra o tipo de rastro do ViewCapture para 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

Exemplo completo

O Perfetto permite coletar dados de várias fontes em uma única configuração. É possível reunir todos os rastros do Winscope usando um único 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

Capturar rastros no Android 14 e versões anteriores

Execute adb root antes de executar os comandos adb shell para cada um dos rastros a seguir. No final do rastro, os arquivos de rastro ficam disponíveis em /data/misc/wmtrace. Para copiar um arquivo ou diretório e os subdiretórios dele de um dispositivo, consulte Copiar arquivos de e para um dispositivo.

Rastros do WindowManager

Para capturar rastros do WindowManager:

  • Ativar rastro:

    adb shell wm tracing start

  • Desativar rastro:

    adb shell wm tracing stop

  • Salvar dados de registro no arquivo durante a execução de uma captura de rastro:

    adb shell wm tracing save-for-bugreport

  • Registrar rastro uma vez por frame:

    adb shell wm tracing frame

  • Registrar cada transação:

    adb shell wm tracing transaction

  • Definir o tamanho máximo do registro (em KB):

    adb shell wm tracing size

  • Imprimir o status do rastro:

    adb shell wm tracing status

  • Defina o nível de registro como critical (apenas janelas visíveis com informações reduzidas), trim (todas as janelas com informações reduzidas) ou all (todas as janelas e informações):

    adb shell wm tracing level

Dumps do WindowManager

Para capturar dumps do WindowManager:

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

ProtoLog

Os comandos a seguir são usados para o ProtoLog sistema.

No processo system_server:

  • Iniciar o ProtoLog:

    adb shell cmd window logging start

  • Parar o ProtoLog:

    adb shell cmd window logging stop

  • Ativar o ProtoLog para grupos de registro especificados:

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

  • Desativar o ProtoLog para grupos de registro especificados:

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

  • Ativar o registro do Logcat para grupos de registro especificados:

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

  • Desativar o registro do Logcat para grupos de registro especificados:

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

No WMShell:

  • Iniciar o ProtoLog:

    adb shell dumpsys activity service SystemUIService WMShell

Rastros do SurfaceFlinger (camadas)

O rastreamento de camadas do SurfaceFlinger usa o rastro do Perfetto para captura. Consulte Configuração de rastro para informações de configuração.

O exemplo a seguir mostra uma configuração para rastreamento de camadas do 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
        }
    }
}

O exemplo de comando a seguir gera rastreamento para camadas do SurfaceFlinger:

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

Dumps do SurfaceFlinger (camadas)

Para capturar dumps do SurfaceFlinger, execute o comando a seguir:

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

Transições de shell

Os comandos a seguir são usados para rastreamento de transição.

No processo system_server, use os comandos a seguir:

  • Iniciar um rastro:

    adb shell cmd window shell tracing start

  • Parar um rastro:

    adb shell cmd window shell tracing stop

  • Iniciar um rastro no WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • Parar um rastro no WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

Os comandos a seguir são usados para o rastreamento do editor de método de entrada (IME, na sigla em inglês):

  1. Iniciar o rastreamento do IME para clientes de método de entrada (IM), serviço de método de entrada (IMS) e serviço de gerenciamento de método de entrada (IMMS): adb shell ime tracing start

  • Iniciar o rastreamento de clientes IME, IMS e IMMS:

    adb shell ime tracing stop

SurfaceFlinger (transações)

O rastreamento de transações do SurfaceFlinger usa o rastro do Perfetto para captura. Consulte Configuração de rastro para informações de configuração.

O exemplo a seguir mostra uma configuração do Perfetto para o SurfaceFlinger rastreamento ativo:

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

O exemplo a seguir mostra uma configuração do Perfetto para o SurfaceFlinger rastreamento contínuo:

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

O exemplo de comando a seguir gera rastreamento para transações do SurfaceFlinger:

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