O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Esta página foi traduzida pela API Cloud Translation.

Capturar rastros com comandos adb

Os rastros 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 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 você pode 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 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 o mínimo de sobrecarga de desempenho.
Frequência de registro (log_frequency): define a frequência em 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

Confira a seguir um exemplo do 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 no group_overrides.
ENABLE_ALL: rastreia todos os grupos e níveis de registro, a menos que especificado no 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 nível será rastreada, a menos que uma substituição de grupo seja especificada. Por exemplo, ele é 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 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 do ProtoLog no grupo que está sendo rastreado.

Aviso: o registro de rastros de pilha é lento e afeta o desempenho do dispositivo. Esse recurso é mais adequado para o desenvolvimento local.

Exemplo

Confira a seguir um exemplo do tipo de trace 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 rastreamento (trace_mode): determina se o rastreamento de entrada precisa ser iniciado usando regras de preservação de privacidade ou se todos os eventos de entrada precisam ser registrados:

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 rastro.

Exemplo

Confira a seguir um exemplo do tipo de trace 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 uma camada é alterada.
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 é limpa.
MODE_DUMP: traça um snapshot de camadas únicas.
MODE_GENERATED_BUGREPORT_ONLY: igual a MODE_GENERATED, mas aciona a geração de snapshots de camadas somente quando um relatório de bug é feito, não sempre que um rastro é apagado.

Flags de rastreamento (trace_flags):

TRACE_FLAG_INPUT: se a plataforma contém dados de entrada, rastreia as especificações 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.

Aviso: esse campo é muito detalhado e requer uma grande quantidade de memória.
TRACE_FLAG_HWC: rastreia outros metadados não estruturados do compositor de hardware.

Aviso: esse campo é muito detalhado e requer uma grande quantidade de memória.
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

Confira a seguir um exemplo do tipo de rastreamento 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 rastro não tem opções de configuração.

Exemplo

Confira a seguir um exemplo do tipo de trace de transição do 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 traço.

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 é limpa. 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 origem de dados seja interrompida.

Exemplo

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

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

Confira a seguir um exemplo do tipo de trace de 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 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 rastros. No final do rastreamento, os arquivos de rastreamento 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 o rastreamento:
```
adb shell wm tracing start
```
Desativar o rastreamento:
```
adb shell wm tracing stop
```
Salve os dados de registro em um arquivo durante a execução de uma captura de rastro:
```
adb shell wm tracing save-for-bugreport
```
Registrar o rastro 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 o status do trace:
```
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
```

Despejos 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 o 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 registro:
```
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 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 rastreamento para informações de configuração.

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

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

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

Despejos do SurfaceFlinger (camadas)

Para capturar despejos do SurfaceFlinger:

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

Transições de shell

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

No processo system_server:

Inicie um rastro:

adb shell cmd window shell tracing start

Interromper um rastro:

adb shell cmd window shell tracing stop

Inicie um rastreamento no WMShell:

adb shell dumpsys activity service SystemUIService WMShell transitions tracing start

Interromper 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):

Inicie o rastreamento de 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 rastro 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
        }
    }
}

Consulte o exemplo de comando abaixo para gerar o rastreamento de transações do SurfaceFlinger:

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