perfetto

O perfetto é uma ferramenta que permite coletar informações de desempenho de dispositivos Android pelo Android Debug Bridge (adb). Invoque a ferramenta perfetto usando o comando adb shell perfetto .... O perfetto usa várias fontes para coletar rastros de desempenho do dispositivo, como:

  • ftrace para informações do kernel
  • atrace para anotações de espaço do usuário em serviços e apps
  • heapprofd para informações de uso de memória nativa por serviços e apps

Esta página descreve como chamar o perfetto e o configurar para gerar a saída que você quer. Para mais informações, consulte a documentação do perfetto (link em inglês).

Sintaxe

Esta seção descreve como usar o adb para chamar o perfetto para diferentes modos e gerar um rastro.

Seleção da origem de dados

O perfetto inclui os dois modos abaixo que determinam as origens de dados usadas para registrar o rastro:

  • Modo Light: pode selecionar apenas um subconjunto de fontes de dados, especificamente atrace e ftrace. No entanto, esse modo oferece uma interface semelhante ao systrace.
  • Modo Normal: recebe a configuração em um buffer de protocolo e permite aproveitar mais da funcionalidade do perfetto usando fontes de dados diferentes de atrace eftrace.

Opções gerais

A tabela abaixo lista as opções disponíveis quando o perfetto é usado em qualquer um dos modos:

Tabela 1. Lista de opções gerais disponíveis da ferramenta perfetto.

Opção Descrição
--background |
-d
O perfetto sai imediatamente da interface da linha de comando e continua registrando o rastro em segundo plano.
--background-wait | -D Como --background, mas aguarda (até um máximo de 30 segundos) todas as fontes de dados começarem antes de sair. O código de saída pode ser zero em caso de uma confirmação bem-sucedida ou diferente de zero (erro ou tempo limite).
--alert-id ID do alerta que acionou esse rastro.
--config-id ID da configuração de acionamento.
--config-uid UID do app que registrou a configuração.
--subscription-id ID da assinatura que acionou esse rastro.
--out OUT_FILE |
-o OUT_FILE

Especifica o caminho desejado para o arquivo de rastreamento de saída ou - para stdout. perfetto grava a saída no arquivo descrito nas sinalizações anteriores. O formato de saída é compilado com o formato definido no trace.proto do AOSP.

Observação: especifique o nome completo do caminho do arquivo de saída. Normalmente, os arquivos precisam ser gravados na pasta /data/misc/perfetto-traces.

--upload Após a conclusão, transmita o rastro para o pacote especificado pela mensagem IncidentReportConfig na configuração do rastro do proto.
--no-guardrails Desativa a proteção contra usa excessivo de recursos ao ativar a sinalização --upload durante os testes.
--reset-guardrails Redefine o estado persistente das proteções e saídas para testes.
--rsave-for-bugreport Se um rastro com bugreport_score > 0 estiver em execução, ele vai ser salvo em um arquivo. Mostra o caminho quando concluído.
--query Consulta e mostra o estado do serviço em um texto legível.
--query-raw É semelhante a --query, mas mostra bytes brutos codificados em .proto de tracing_service_state.proto.
--help | -h Mostra textos de ajuda para a ferramenta perfetto.

Modo Light

A sintaxe geral para usar o perfetto no modo Light é esta:

 adb shell perfetto [ --time TIMESPEC ] [ --buffer SIZE ] [ --size SIZE ]
             [ ATRACE_CAT | FTRACE_GROUP/FTRACE_NAME | FTRACE_GROUP/* ]...
             --out FILE

A tabela abaixo lista as opções disponíveis quando o perfetto é usado no modo Light:

Tabela 2. Lista de opções da ferramenta perfetto disponíveis ao usar o modo Light.

Opção Descrição
--time TIME[s|m|h] |
-t TIME[s|m|h]
Especifica a duração do trace em segundos, minutos ou horas. Por exemplo, --time 1m especifica uma duração de trace de 1 minuto. A duração padrão é de 10 segundos.
--buffer SIZE[mb|gb] |
-b SIZE[mb|gb]
Especifica o tamanho do buffer do anel em megabytes (mb) ou gigabytes (gb). O parâmetro padrão é --buffer 32mb.
--size SIZE[mb|gb] |
-s SIZE[mb|gb]
Especifica o tamanho máximo do arquivo em megabytes (mb) ou gigabytes (GB). Por padrão, perfetto usa apenas o buffer de anel na memória.
--app | -a Nome do app Android (atrace)

Essas opções são seguidas por uma lista de especificadores de eventos:

Tabela 3. Lista de especificadores de eventos para o modo Light.

Evento Descrição
ATRACE_CAT Especifica as categorias do atrace para as quais você quer registrar um rastro. Por exemplo, o comando abaixo rastreia o gerenciador de janelas usando o atrace:
    adb shell perfetto --out FILE wm
    

Para registrar outras categorias, consulte esta lista de categorias de atrace.

FTRACE_GROUP/FTRACE_NAME Especifica os eventos do ftrace para os quais você quer registrar um rastro. Por exemplo, o comando abaixo rastreia eventos sched/sched_switch:
      adb shell perfetto --out FILE sched/sched_switch
      

Modo Normal

A sintaxe geral para usar o perfetto no modo Normal é esta:

 adb shell perfetto [ --txt ] --config CONFIG_FILE --out FILE

A tabela abaixo lista as opções disponíveis quando perfetto é usado no modo Normal:

Tabela 4. Lista de opções da ferramenta perfetto disponíveis ao usar o modo Normal.

Opção Descrição
--config CONFIG_FILE | -c CONFIG_FILE Especifica o caminho para um arquivo de configuração. No modo normal, algumas configurações podem ser codificadas em um buffer de protocolo de configuração. Esse arquivo precisa obedecer ao esquema de buffer de protocolo definido no trace_config.proto do AOSP.

As fontes de dados são selecionadas e configuradas usando o membro DataSourceConfig de TraceConfig, conforme definido no data_source_config.proto do AOSP.

--txt Instrui o perfetto a analisar o arquivo de configuração como pbtxt. Essa sinalização é destinada apenas a testes locais. Não é recomendável ativá-la para produção.

Origens de dados compatíveis

Esta seção descreve as diferentes origens que o perfetto usa para gerar o rastro.

ftrace

A fonte de dados ftrace permite que o perfetto receba eventos do kernel.

Ative essa fonte configurando ftrace_config no DataSourceConfig.

Os eventos que podem ser ativados incluem:

  • Programar atividade:

    • sched/sched_switch
    • sched/sched_wakeup
    • sched/sched_wakeup_new
    • sched/sched_process_exec
    • sched/sched_process_exit
    • sched/sched_process_fork
    • sched/sched_process_free
    • sched/sched_process_hang
    • sched/sched_process_wait
  • Eventos do Filesystem:

  • Eventos atrace

Dependendo do dispositivo, da versão do SO ou do kernel, mais eventos podem estar disponíveis. Para mais informações, consulte os protos de configuração.

Estatísticas de processo

A origem de dados de estatísticas do processo permite que você confira os contadores consultados sobre o sistema e os processos individuais.

Ative essa origem configurando process_stats_config e sys_stats_config na DataSourceConfig.

Os dados que o perfetto gera incluem:

Dependendo do dispositivo, da versão do SO e do kernel, mais eventos podem estar disponíveis. Para saber mais, consulte os protótipos de configuração para sys_stats e process_stats.

heapprofd

heapprofd permite criar uma amostra das causas do uso de memória nativa.

Ative essa fonte configurando heapprofd_config no DataSourceConfig. Essa configuração produz ProfilePackets, incluindo os frames Java da pilha de chamadas.

Outras informações sobre como usar heapprofd podem ser encontradas em perfetto.dev (link em inglês).

Outras origens

Dependendo do dispositivo, do kernel e da versão do SO, mais origens de dados podem estar disponíveis. Para saber mais, consulte os protos de configuração da origem de dados.

Mais informações sobre perfetto podem ser encontradas em perfetto.dev (link em inglês).