Comandos de depuração para criação de perfil local

Ao testar a integração do ProfilingManager localmente, as solicitações podem ser limitadas por limitação de taxa ou os traces em segundo plano podem não estar ativos ao testar acionadores. Use os comandos adb nesta página para desativar a limitação, extrair perfis, reter traces não editados, acionar capturas e inspecionar o estado do serviço em um dispositivo de teste.

Desativar o limitador de taxa

Para desativar os limitadores de taxa do sistema e do processo do app para solicitações de requestProfiling durante o teste local, execute o seguinte comando device_config:

adb shell device_config put profiling_testing rate_limiter.disabled true

Quando terminar o teste, redefina a flag:

adb shell device_config delete profiling_testing rate_limiter.disabled

Observação: rate_limiter.disabled se aplica apenas a chamadas requestProfiling orientadas por apps. Ao testar acionadores localmente, defina system_triggered_profiling.testing_package_name para forçar um rastro contínuo em segundo plano e ignorar o limitador de taxa no nível do sistema, conforme mostrado em Forçar a ativação de rastros em segundo plano para testes de acionadores.

Extrair perfis usando o ADB

Para inspecionar um perfil editado localmente em um dispositivo com acesso root, execute adb pull com o caminho retornado por getResultFilePath:

# Pull a profile
adb pull /data/user/0/<com.example.myapp>/files/profiling/<profile-file-name>

Observação: se você não tiver acesso root, poderá configurar o ProfilingManager para reter perfis em /data/misc/perfetto-traces/profiling/, que pode ser acessado usando adb pull em todos os tipos de build no Android 16 (nível da API 36) e versões mais recentes. Consulte Reter resultados temporários e não editados.

Reter resultados temporários e não editados

Ao testar a criação de perfil localmente, é possível reter os resultados no diretório temporário em /data/misc/perfetto-traces/profiling/. Comparar um rastreamento do sistema não editado com a versão editada ajuda a entender quais dados são removidos durante a edição.

A forma como os resultados temporários e não editados são retidos depende da versão do Android que seu dispositivo usa:

• Android 16 (nível 36 da API) e versões mais recentes: é possível manter os resultados não editados (quando aplicável) e editados no diretório temporário, que foi expandido no Android 16 para ser acessível usando adb pull em todos os tipos de build sem acesso root (enquanto o Android 15 exige acesso root para ler /data/misc/perfetto-traces/profiling/). Para evitar que o sistema exclua resultados temporários, execute o seguinte comando:

  adb shell device_config put profiling_testing delete_temporary_results.disabled true
  

• Android 15 (nível 35 da API): no diretório temporário, é possível manter apenas o resultado não editado, que pode ser acessado por adb apenas em builds com acesso root. O app ainda recebe o perfil editado no próprio diretório /data/user/0/<app>/files/profiling/, que o código do app pode ler ou copiar em qualquer build, embora a extração direta de /data/user/0/... com adb pull exija acesso root ou adb shell run-as <app> em um build depurável. Para evitar que o sistema exclua traces não editados, execute o seguinte comando:

  adb shell device_config put profiling_testing delete_unredacted_trace.disabled true
  

Depois de capturar um perfil, extraia o arquivo retido do diretório temporário:

# Pull a retained redacted profile (Android 16 and higher)
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.<profile-type-ext>

# Pull an unredacted system trace
adb pull /data/misc/perfetto-traces/profiling/<trace-name>.perfetto-trace-unredacted

Nesses comandos, <trace-name> é o nome de arquivo base (sem extensão) do caminho retornado por ProfilingResult.getResultFilePath, e a cópia do rastreamento do sistema não editada adiciona -unredacted à extensão .perfetto-trace. Para detalhes sobre a estrutura do nome de arquivo e os valores de <profile-type-ext>, consulte Locais de arquivos e formatos de nomenclatura.

Observação: a retenção de resultados temporários e não editados é desativada por padrão para conservar o armazenamento do dispositivo e é destinada apenas a testes locais. Os rastreamentos do sistema não editados usam mais espaço de armazenamento porque incluem atividades de processo em todo o sistema. Quando terminar o teste, reative a exclusão automática:

adb shell device_config delete profiling_testing delete_temporary_results.disabled
adb shell device_config delete profiling_testing delete_unredacted_trace.disabled

Forçar a ativação de traces em segundo plano para testes de acionadores

Como os traces em segundo plano do sistema são executados em intervalos aleatórios na produção, pode ser difícil testar a criação de perfil baseada em acionadores localmente. Para forçar o sistema a executar um rastro contínuo em segundo plano e ignorar o limitador de taxa no nível do sistema para os acionadores do app, defina system_triggered_profiling.testing_package_name:

adb shell device_config put profiling_testing system_triggered_profiling.testing_package_name <com.example.myapp>

Qualquer período de espera por gatilho configurado com setRateLimitingPeriodHours ainda é válido. Como esse modo é executado continuamente até que você o limpe, remova a flag quando terminar o teste:

adb shell device_config delete profiling_testing system_triggered_profiling.testing_package_name

Comandos úteis de depuração

No Android 16 (nível 36 da API) e versões mais recentes com uma versão recente do módulo Profiling, é possível usar a ferramenta cmd profiling_service em adb para ativar a geração de registros detalhados, acionar coletas de perfis sob demanda e testar acionadores diretamente na linha de comando.

Dica: outras opções podem existir ou ser adicionadas ao longo do tempo. Execute adb shell cmd profiling_service help para ver todos os comandos, flags e detalhes de uso de depuração disponíveis.

Ativar a geração de registros de depuração detalhados

Para ativar os registros detalhados do ProfilingService no logcat e diagnosticar o processamento e a entrega de solicitações, execute o seguinte comando:

adb shell cmd profiling_service enable-logs true

Solicitar uma coleção de perfis on demand

Para iniciar uma captura de perfil imediata para um pacote específico na linha de comando, execute o seguinte comando:

adb shell cmd profiling_service request-profiling <profiling_type> <com.example.myapp> [--user <user_id>] [--duration <duration_ms>] [--sources <sources>]

Nesse comando, <profiling_type> é o valor constante inteiro de ProfilingManager (1 para um heap dump do Java, 2 para um perfil de alocação heap, 3 para amostragem de pilha ou 4 para um rastreamento do sistema). O processo do app de destino precisa estar em execução para perfis de memória e pilha, a solicitação está sujeita ao limitador de taxa, a menos que esteja desativado, e o ProfilingResult concluído é entregue apenas a listeners globais registrados com registerForAllProfilingResults.

Registrar e simular gatilhos

Para registrar um acionador ou disparar um evento de acionador simulado para um pacote e verificar o processamento de callback do acionador, execute os seguintes comandos:

adb shell cmd profiling_service add-trigger <trigger_type> <com.example.myapp> [--user <user_id>]
adb shell cmd profiling_service trigger <trigger_type> <com.example.myapp> [--user <user_id>]

Nesses comandos, <trigger_type> é o valor constante inteiro de ProfilingTrigger (por exemplo, 1 para TRIGGER_TYPE_APP_FULLY_DRAWN, 2 para TRIGGER_TYPE_ANR ou 7 para TRIGGER_TYPE_OOM). A execução de add-trigger registra o acionador com um período de espera de 0 horas, substituindo qualquer registro atual para esse tipo de acionador. A simulação de acionadores que salvam um snapshot do rastro em segundo plano (como 1 ou 2) requer um rastro em segundo plano ativo (consulte Forçar a ativação de rastros em segundo plano para testes de acionadores).

Coletar o estado geral do ProfilingManager

No Android 16 (nível 36 da API) e versões mais recentes com uma versão recente do módulo Profiling, é possível executar dumpsys em profiling_service para diagnosticar problemas e inspecionar o estado atual de ProfilingManager:

adb shell dumpsys profiling_service

A saída dumpsys profiling_service é destinada apenas para fins informativos e de depuração, e o formato dela está sujeito a alterações. Ele fornece um snapshot do estado interno do serviço, incluindo:

• Limitações ativas e status do limitador de taxa.
• Configurações de dispositivos ativos.
• Acionadores de apps registrados e os períodos de espera de limitação de taxa.
• Sessões de criação de perfil ativas e em fila.
• Solicitações de criação de perfil recentes, ocorrências de acionadores e eventos de entrega de resultados.

Dica: para reter um histórico mais longo de eventos recentes na saída de dumpsys durante sessões de depuração estendidas, execute adb shell cmd profiling_service enable-long-dumpsys true.