Capturar rastros com comandos adb

Os rastreamentos do Winscope podem ser coletados com 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 rastreamentos do Winscope são integrados ao Perfetto e coletados usando a linha de comando do Perfetto. Cada rastreamento 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 rastreamento do Winscope tem um comando diferente, e é possível coletar cada um de forma independente. Consulte Capturar rastreamentos 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 rastreamento.

Opções de configuração

  • Nível de registro (log_level): especifica o nível de detalhes do registro. Valores aceitos:

    • 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 mais detalhes sobre os valores de configuração.

Exemplo

Confira um exemplo do tipo de rastreamento 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 rastreamento.

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 registros especificados no group_overrides.
  • ENABLE_ALL: rastreia todos os grupos e níveis de registros, a menos que especificado em group_overrides.

Nível mínimo de registro (default_log_from_level): se definido, qualquer mensagem com um nível de registro maior ou igual a esse será rastreada, a menos que uma substituição de grupo seja especificada. Por exemplo, isso é usado para ativar o registro de todos os avisos e erros sem precisar ativar todos os registros. Os valores aceitos 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 do 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 rastreamento de pilha de cada mensagem ProtoLog no grupo rastreado.

Exemplo

Confira a seguir um exemplo do tipo de rastreamento 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 rastreamento.

Opções de configuração

Modo de rastreamento (trace_mode): determina se o rastreamento de entrada deve ser iniciado usando regras de preservação da privacidade ou registrar todos os eventos de entrada:

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

Exemplo

Confira um exemplo do tipo de rastreamento 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 rastreamento.

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 é capturado sempre que uma mudança de camadas ocorre.
  • 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 somente quando um relatório de bug é criado, não sempre que um rastreamento é liberado.

Flags de rastreamento (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 adicionais da superfície, incluindo camadas fora da tela.

  • TRACE_FLAG_HWC: rastreia outros metadados 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 somente quando ocorrem alterações de geometria.

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

Exemplo

Confira a seguir um exemplo do tipo de rastreamento 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 rastreamento.

Opções de configuração

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

Exemplo

Confira a seguir um exemplo do tipo de rastreamento 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 rastreamento.

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

Veja a seguir um exemplo do tipo de rastreamento 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 rastreamento.

Opções de configuração

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

Exemplo

Confira a seguir um exemplo do tipo de rastreamento 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 rastreamento.

Opções de configuração

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

Exemplo

Confira a seguir um exemplo do tipo de rastreamento 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

Com o Perfetto, é possível coletar dados de várias fontes em uma única configuração. É possível reunir todos os rastreamentos do Winscope com 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 em versões anteriores

Execute adb root antes de executar os comandos adb shell para cada um dos seguintes rastreamentos. No final do rastreamento, os arquivos 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.

Rastreamentos do WindowManager

Para capturar rastreamentos do WindowManager:

  • Ativar rastreamento:

    adb shell wm tracing start

  • Desativar o rastreamento:

    adb shell wm tracing stop

  • Salvar dados de registro em arquivo durante a execução de uma captura de rastreamento:

    adb shell wm tracing save-for-bugreport

  • Registrar o rastreamento uma vez por frame:

    adb shell wm tracing frame

  • Registre cada transação:

    adb shell wm tracing transaction

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

    adb shell wm tracing size

  • Imprimir status do rastreamento:

    adb shell wm tracing status

  • Defina o nível de registro como critical (somente 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 despejos do WindowManager:

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

ProtoLog

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

No processo system_server:

  • Iniciar ProtoLog:

    adb shell cmd window logging start

  • Parar ProtoLog:

    adb shell cmd window logging stop

  • Ative o ProtoLog para determinados grupos de registros:

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

  • Desative o ProtoLog para determinados grupos de registros:

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

  • Ative a geração de registros do Logcat para determinados grupos de registros:

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

  • Desative a geração de registros do Logcat para determinados grupos de registros:

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

No WMShell:

  • Iniciar ProtoLog:

    adb shell dumpsys activity service SystemUIService WMShell

Rastreamentos do SurfaceFlinger (camadas)

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

Confira o exemplo a seguir de uma configuração para rastreamento de camada 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
        }
    }
}

Confira o exemplo de comando a seguir para gerar rastreamento de camadas do SurfaceFlinger:

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

Despejos do SurfaceFlinger (camadas)

Para capturar dumps do SurfaceFlinger:

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:

  • Inicie um rastreamento:

    adb shell cmd window shell tracing start

  • Parar um rastreamento:

    adb shell cmd window shell tracing stop

  • Inicie um rastreamento no WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

  • Interromper um rastreamento no WMShell:

    adb shell dumpsys activity service SystemUIService WMShell transitions tracing stop

IME

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

  • Inicie 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

  • Comece a rastrear clientes IME, IMS e IMMS:

    adb shell ime tracing stop

SurfaceFlinger (transações)

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

Confira o exemplo a seguir de uma configuração do Perfetto para rastreamento ativo do 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

Confira o exemplo a seguir de uma configuração do Perfetto para o rastreamento contínuo do 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
        }
    }
}

Confira o exemplo de comando a seguir para gerar rastreamento de transações do SurfaceFlinger:

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