Gerar um rastro do sistema em um dispositivo

Dispositivos com o Android 9 (nível 28 da API) ou mais recente incluem um app de nível de sistema chamado Rastreamento do sistema. Ele é parecido com o utilitário de linha de comando systrace, mas permite que você grave os rastros diretamente de um dispositivo de teste, sem precisar conectá-lo pelo adb. Você pode usar o app para compartilhar os resultados desses rastros com sua equipe de desenvolvimento.

Dispositivos com o Android 10 e mais recentes gravam rastros no formato do Perfetto, enquanto dispositivos anteriores fazem a gravação no formato do Systrace. Recomendamos o uso do leitor de rastros do Perfetto para abrir os dois formatos e analisar os rastros.

Ele ajuda a gravar rastros de processamento de bugs relacionados ao desempenho do app, como inicialização lenta, transições lentas ou instabilidade da interface.

Gravar um rastro do sistema

O app Rastreamento do sistema usa o bloco "Configurações rápidas" ou um menu próprio para gravar um rastro do sistema. As próximas seções descrevem como realizar o processo de gravação usando essas interfaces.

Observação: como parte do seu fluxo de trabalho de desenvolvimento, você pode enviar um relatório de bugs no dispositivo. É importante enviar esse tipo de relatório de bugs depois de terminar de gravar um rastro do sistema. Dessa forma, o processo do relatório em si não fica incluído no rastro gravado.

Gravar usando o bloco "Configurações rápidas"

Normalmente, o bloco "Configurações rápidas" é a maneira mais conveniente de concluir o processo de rastreamento do sistema no dispositivo.

Configurar o bloco

Se você estiver usando o Rastreamento do sistema pela primeira vez no seu dispositivo de teste ou se não encontrar o bloco Rastreamento do sistema no painel Configurações rápidas do dispositivo (Figura 2), siga estas etapas de configuração:

1. Ative as Opções do desenvolvedor.
2. Abra a tela de configurações das Opções do desenvolvedor.
3. Na seção Depuração, selecione Rastreamento do sistema. O Rastreamento do sistema será aberto, mostrando o menu do app.

4. No menu do app, ative a opção Mostrar bloco "Configurações rápidas", como mostrado na Figura 1. O sistema adicionará o bloco Rastreamento do sistema ao painel Configurações rápidas, conforme mostrado na Figura 2:

   

   Figura 1. Opção Mostrar bloco "Configurações rápidas" no app Rastreamento do sistema.

   

   Figura 2. Bloco Rastreamento do sistema no painel Configurações rápidas.

   Observação: por padrão, o sistema adiciona o bloco Rastreamento do sistema como o primeiro bloco no painel Configurações rápidas. Se você quiser que ele apareça em uma posição diferente, use o modo de edição para movê-lo.

Concluir uma gravação de rastro do sistema

Para gravar um rastro do sistema usando o painel Configurações rápidas, siga estas etapas:

1. Toque no bloco Rastreamento do sistema, que tem a etiqueta Gravar rastro. O bloco será ativado, e uma notificação contínua será exibida para informar que o sistema está gravando um rastro, como mostrado na Figura 3:

   

   Figura 3. Notificação contínua exibida após o início do rastreamento do sistema no dispositivo.

2. Execute no app as ações que você quer que o sistema inspecione.

   Observação: para registrar bugs difíceis de reproduzir, deixe o Rastreamento do sistema aberto em segundo plano e interrompa-o logo depois do bug. O app vai salvar a atividade do dispositivo em um buffer contínuo, que armazena de 10 a 30 segundos de eventos.

3. Para interromper o rastreamento, toque no bloco Rastreamento do sistema no painel Configurações rápidas ou na notificação do app Rastreamento do sistema.

   O sistema mostrará uma nova notificação com a mensagem "Salvando rastro". Em seguida, o sistema vai dispensar essa notificação e mostrar uma terceira confirmando que seu rastro foi salvo e que está tudo pronto para compartilhar o rastro do sistema, conforme mostrado na Figura 4:

   

   Figura 4. Notificação contínua que aparece depois que o sistema termina de salvar um rastro gravado.

Gravar usando o menu do app

O menu do app permite definir várias configurações avançadas relacionadas ao rastreamento do sistema e oferece uma opção para iniciar e interromper o processo.

Para gravar um rastro do sistema usando o menu do app Rastreamento do sistema, siga estas etapas:

1. Ative as Opções do desenvolvedor.

2. Abra a tela de configurações das Opções do desenvolvedor. Na seção Depuração, selecione Rastreamento do sistema. O app Rastreamento do sistema vai ser aberto.

   Como alternativa, se você tiver configurado o bloco Rastreamento do sistema, toque nele e mantenha-o pressionado para entrar no app Rastreamento do sistema.

3. Confira se a opção Rastrear aplicativos depuráveis está selecionada para incluir apps que tenham a depuração ativada no rastro do sistema.

4. É possível escolher as Categorias de chamadas do sistema e do sensor que você quer rastrear, bem como um Tamanho de buffer por CPU em KB. Escolha categorias que correspondam ao caso de uso sendo testado, como a categoria de Áudio para testar operações Bluetooth ou a categoria de Memória para alocações de heap.

   Observação: essas categorias servem como configurações no nível do app, de modo que o sistema também as utiliza no bloco Configurações rápidas. Além disso, essas configurações são preservadas em todas as reinicializações do dispositivo.

5. É possível selecionar rastros longos para ativar rastros que são salvos continuamente no armazenamento do dispositivo. Para essa opção, defina limites para o Tamanho máximo do rastro longo e a Duração máxima do rastro longo.

6. Ative a opção Gravar rastro, destacada na Figura 5. O bloco será ativado, e uma notificação contínua será exibida para informar que o sistema está gravando um rastro, como mostrado na Figura 3.

   

   Figura 5. Opção Gravar rastro nas configurações do Rastreamento do sistema.

7. Execute no app as ações que você quer que o sistema inspecione.

   Observação: para registrar bugs difíceis de reproduzir, deixe o Rastreamento do sistema aberto em segundo plano e interrompa-o logo depois do bug. Por padrão, o Rastreamento do sistema salva a atividade do dispositivo em um buffer contínuo que armazena de 10 a 30 segundos de eventos. Se os rastros longos estiverem ativados, a atividade do dispositivo será salva continuamente no armazenamento do dispositivo até os limites definidos.

8. Interrompa o rastreamento desativando a opção Gravar rastro.

   O sistema mostrará uma nova notificação com a mensagem "Salvando rastro". Em seguida, o sistema vai dispensar essa notificação e mostrar uma terceira confirmando que seu rastro foi salvo e que está tudo pronto para compartilhar o rastro do sistema, conforme mostrado na Figura 4.

Compartilhar um rastro do sistema

O app Rastreamento do sistema ajuda a compartilhar os resultados de rastros do sistema como parte de vários fluxos de trabalho diferentes. Nos dispositivos com o Android 10 (nível 29 da API) ou mais recente, os arquivos de rastros são salvos com a extensão de nome de arquivo .perfetto-trace e podem ser abertos na interface do Perfetto. Nos dispositivos com uma versão anterior do Android, os arquivos de rastros são salvos com a extensão .ctrace, que indica o formato do Systrace.

Compartilhar como mensagem

O Rastreamento do sistema permite compartilhar o rastro coletado com outros apps no dispositivo. Ao fazer isso, você pode enviar o rastro para sua equipe de desenvolvimento por e-mail ou um app de rastreamento de bugs, sem precisar conectar o dispositivo à máquina de desenvolvimento.

Depois de gravar um rastro do sistema, toque na notificação que aparece no dispositivo, como a mostrada na Figura 4. O seletor de intents da plataforma é mostrado, permitindo compartilhar o rastro usando o app de mensagens que você preferir.

Compartilhar pelo app Files

Em dispositivos com o Android 10 (nível 29 da API) ou mais recente, os rastros são mostrados no app Files. É possível compartilhar um rastro usando esse app.

Fazer o download do relatório usando adb

Você também pode extrair um rastro do sistema de um dispositivo usando o adb. Conecte o dispositivo usado para gravar o rastro na máquina de desenvolvimento e execute os comandos abaixo em uma janela do terminal:

cd /path-to-traces-on-my-dev-machine && \
  adb pull /data/local/traces/ .

Converter formatos de rastros

Você pode converter arquivos de rastreamento do Perfetto para o formato Systrace. Consulte Como converter entre os formatos de rastros para mais informações.

Criar um relatório HTML

Ao compartilhar seu rastro, o relatório fica em um arquivo .perfetto-trace em dispositivos com Android 10 ou mais recente ou em um arquivo .ctrace nas outras versões.

Crie um relatório HTML com base no arquivo de rastreamento usando uma interface baseada na Web ou uma linha de comando.

IU baseada na Web

Use a IU do Perfetto (link em inglês) para abrir o arquivo de rastreamento e gerar o relatório.

No caso de um arquivo do Perfetto, clique em Open trace file. Para um arquivo do Systrace, clique em Open with legacy UI. A IU legada tem a mesma aparência do relatório do Systrace.

Linha de comando

Execute os comandos abaixo na janela de terminal para gerar um relatório HTML no arquivo de rastreamento:

cd /path-to-traces-on-my-dev-machine && \
  systrace --from-file trace-file-name{.ctrace | .perfetto-trace}

Se você ainda não tiver o programa de linha de comando systrace, faça o download a partir do Catapult (link em inglês) projeto no GitHub ou diretamente do Android Open Source projeto.