Gerar um rastro do sistema em um dispositivo

Dispositivos com o Android 9 (nível 28 da API) ou versões mais recentes incluem um app de nível de sistema chamado Rastreamento do sistema. Esse app é parecido com o utilitário de linha de comando systrace, mas permite que você registre os rastros diretamente de um dispositivo de teste, sem precisar conectar o dispositivo por cabo e por ADB. Você pode usar o app para compartilhar os resultados desses rastros com sua equipe de desenvolvimento.

Registrar os rastros é especialmente útil ao lidar com bugs de performance no app, como instabilidade da IU, inicialização ou transições lentas.

Registrar um rastro do sistema

O app Rastreamento do sistema permite registrar um rastro do sistema usando as "Configurações rápidas" ou um menu dentro do próprio app. As próximas seções descrevem como realizar o processo de registro usando essas interfaces.

Registrar usando o bloco Configurações rápidas

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

Configurar o bloco

Figura 2. Botão Mostrar bloco de Configurações rápidas no app Rastreamento do sistema

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 1), siga as etapas de configuração abaixo:

  1. Ative as opções do desenvolvedor, caso ainda não tenha feito isso.
  2. Abra a tela de configurações de Opções do desenvolvedor.
  3. Na seção Depuração, selecione Rastreamento do sistema. O app Rastreamento do sistema vai ser aberto e o menu do app é mostrado.

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

    Figura 1. 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, use o modo de edição para mover o bloco para que ele apareça em outra posição.

Concluir um registro de rastro do sistema

Para registrar um rastro do sistema usando o painel Configurações rápidas, siga as etapas abaixo:

  1. Toque no bloco Rastreamento do sistema, que tem o marcador "Registrar rastros". O bloco vai ser ativado, e uma notificação contínua será mostrada para informar que o sistema está registrando um rastro, como mostrado na Figura 3:

    Notificação com a mensagem "O rastro está sendo gravado. Toque para parar o rastreamento".
    Figura 3. Notificação contínua mostrada após o início da geração de um rastro do sistema no dispositivo

  2. Realize as ações no app que você gostaria que o sistema inspecionasse.

  3. Quando concluir essas ações, pare o rastreamento tocando no bloco Rastreamento do sistema no painel Configurações rápidas ou na notificação do Rastreamento do sistema.

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

    Notificação com a mensagem "Rastros salvos. Toque para compartilhar seus rastros".
    Figura 4. Notificação contínua que aparece depois que o sistema termina de salvar um rastro registrado.

Registrar usando o menu do app

O menu do app permite que você defina várias configurações avançadas relacionadas à geração de rastros do sistema e oferece uma opção para iniciar e interromper um rastro.

Para registrar um rastro do sistema usando o menu do app Rastreamento do sistema, siga as etapas abaixo:

  1. Ative as opções do desenvolvedor, caso ainda não tenha feito isso.

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

    Como alternativa, se tiver configurado o bloco Rastreamento do sistema, você pode manter o bloco pressionado para entrar no app Rastreamento do sistema.

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

  4. Há a opção de escolher as Categorias de chamadas do sistema e do sensor a serem rastreadas e escolher um Tamanho do 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 Memória para alocações de heap.

    Figura 5. Opção Registrar rastros no app Rastreamento do sistema

  5. Há a opção de selecionar os rastros longos para ativar rastros que são salvos continuamente no armazenamento do dispositivo. Para essa opção, é necessário definir limites para o Tamanho máximo do rastro longo e a Duração máxima do rastro longo.

  6. Ative a opção Registrar rastros, destacada na Figura 5. O bloco vai ser ativado e uma notificação contínua vai aparecer para informar que o sistema está registrando um rastro (Figura 3).

  7. Realize as ações no app que você gostaria que o sistema inspecionasse.

  8. Quando concluir essas ações, pare o rastreamento desativando a chaveRegistrar rastros.

    O sistema mostra uma nova notificação com a mensagem "Salvando rastros". Após salvar, o sistema vai dispensar essa notificação e mostrar uma terceira notificação, confirmando que o rastreamento 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 você 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 versões mais recentes, os arquivos de rastreamento são salvos com a extensão de arquivo .perfetto-trace e podem ser abertos na IU do Perfetto (link em inglês). Nos dispositivos com uma versão anterior do Android, os arquivos de rastreamento são salvos com a extensão .ctrace, que indica o formato do Systrace.

Compartilhar como mensagem

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

Depois de registrar um rastro do sistema, toque na notificação que aparece no dispositivo (confira a Figura 4). O seletor de intent da plataforma aparece, permitindo que você compartilhe seu rastreamento usando o app de mensagens de sua preferência.

Compartilhar pelo app Arquivos

Em dispositivos com Android 10 (nível 29 da API), os rastros são mostrados no app Arquivos. Caso queira, é possível compartilhar um rastro usando esse app.

Fazer o download do relatório usando ADB

Se você quiser, também pode extrair um rastro do sistema de um dispositivo usando o ADB. Conecte o dispositivo que registrou o rastreamento à sua máquina de desenvolvimento e execute os comandos abaixo em uma janela de 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 formatos de rastreamento (link em inglês) para mais informações.

Criar um relatório HTML

Ao compartilhar seu rastreamento, o relatório fica em um arquivo .perfetto-trace (em dispositivos com Android 10 ou versões mais recentes) ou em um arquivo .ctrace (para as outras versões).

Crie um relatório HTML no arquivo de rastreamento usando uma IU 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}

Caso ainda não tenha o programa de linha de comando systrace, faça o download dele no projeto Catapult (link em inglês) no GitHub ou diretamente no Android Open Source Project.