Gerar registros de rastreamento com a instrumentação do app

Para gerar um rastreamento de método na execução de um app, você pode o instrumentar usando a classe Debug. A instrumentação do app dessa forma oferece mais controle sobre o momento exato em que o dispositivo começa e para de gravar informações de rastreamento. O dispositivo também salva os registros de rastreamento usando os nomes especificados, o que facilita a identificação posterior dos registros. Você pode ver cada registro de rastreamento usando o CPU Profiler do Android Studio.

Também é possível iniciar e interromper o rastreamento no CPU Profiler sem instrumentar o código do app.

Antes de começar a gerar registros de rastreamento, verifique se o app adicionou lógica para salvar os registros de rastreamento no diretório específico do app.

Instrumentar o app

Para criar registros de rastreamento, chame startMethodTracing() onde quiser que o sistema comece a gerar registros de dados de rastreamento.

Na chamada, você pode especificar o nome do arquivo .trace. O sistema salvará esse arquivo em um diretório específico do pacote, destinado a dados persistentes do app, no dispositivo de destino. É o mesmo diretório retornado por getExternalFilesDir() e, na maioria dos dispositivos, está localizado no diretório ~/sdcard/. Esse arquivo contém os dados binários de rastreamento do método e uma tabela de mapeamento com nomes de linhas de execução e métodos. Para interromper o rastreamento, chame stopMethodTracing().

O exemplo a seguir inicia e interrompe a gravação de um registro de rastreamento com o nome sample.trace:

Kotlin

// Starts recording a trace log with the name you provide. For example, the
// following code tells the system to start recording a .trace file to the
// device with the name "sample.trace".
Debug.startMethodTracing("sample")

// The system begins buffering the generated trace data, until your
// application calls <code><a href="/reference/android/os/Debug.html#stopMethodTracing()">stopMethodTracing()</a></code>, at which time it writes
// the buffered data to the output file.
Debug.stopMethodTracing()

Java

// Starts recording a trace log with the name you provide. For example, the
// following code tells the system to start recording a .trace file to the
// device with the name "sample.trace".
Debug.startMethodTracing("sample");
...
// The system begins buffering the generated trace data, until your
// application calls <code><a href="/reference/android/os/Debug.html#stopMethodTracing()">stopMethodTracing()</a></code>, at which time it writes
// the buffered data to the output file.
Debug.stopMethodTracing();

Observe que, se o app chamar startMethodTracing() novamente sem mudar o nome do registro de rastreamento, o registro existente salvo no dispositivo será substituído. Para saber como mudar dinamicamente o nome de cada registro de rastreamento, vá para a seção sobre como salvar vários registros.

Se o sistema alcançar o tamanho máximo do buffer antes da chamada de stopMethodTracing(), o sistema interromperá o rastreamento e enviará uma notificação para o console. Os métodos que iniciam e interrompem rastreamentos funcionam durante todo o processo do app. Ou seja, é possível chamar startMethodTracing() no método onCreate(Bundle) da atividade e chamar stopMethodTracing() no método onDestroy() dessa atividade.

Observe que o app será executado mais lentamente quando a criação do perfil estiver ativada. Ou seja, não é recomendável usar os dados de criação do perfil para determinar tempos absolutos, como "o método foo() leva 2,5 segundos para ser executado". As informações de tempo nos registros de rastreamento são úteis apenas quando comparadas aos registros de rastreamento anteriores para que você possa ver se as mudanças recentes aumentaram ou reduziram o desempenho do app.

Ao implantar em dispositivos executando o Android 5.0 (API de nível 21) ou versões mais recentes, você pode usar a criação do perfil baseada em amostra para criar um perfil com menor impacto sobre o desempenho do tempo de execução. Para ativar a criação do perfil da amostra, chame startMethodTracingSampling(), em vez de chamar startMethodTracing(), com um intervalo de amostragem especificado. O sistema coleta periodicamente as amostras até que o app chame stopMethodTracing().

Salvar vários registros

Se o app iniciar e interromper um rastreamento de método várias vezes sem especificar um novo nome para o registro de rastreamento, o dispositivo substituirá o registro de rastreamento anterior pelo novo. Ou seja, apenas o registro de rastreamento mais recente é mantido. Para salvar vários registros de rastreamento no dispositivo, renomeie dinamicamente o registro de rastreamento toda vez que o app chamar startMethodTracing(). O exemplo abaixo usa a classe SimpleDateFormat para incluir a data e a hora atuais no momento da atribuição de nome a cada registro de rastreamento.

Kotlin

// Uses the <code><a href="/reference/java/text/SimpleDateFormat.html">SimpleDateFormat</a></code> class to create a String with
// the current date and time.
val dateFormat: DateFormat = SimpleDateFormat("dd_MM_yyyy_hh_mm_ss", Locale.getDefault())
val logDate: String = dateFormat.format(Date())
// Applies the date and time to the name of the trace log.
Debug.startMethodTracing("sample-$logDate")

Java

// Uses the <code><a href="/reference/java/text/SimpleDateFormat.html">SimpleDateFormat</a></code> class to create a String with
// the current date and time.
SimpleDateFormat dateFormat =
        new SimpleDateFormat("dd_MM_yyyy_hh_mm_ss", Locale.getDefault());
String logDate = dateFormat.format(new Date());
// Applies the date and time to the name of the trace log.
Debug.startMethodTracing(
        "sample-" + logDate);

Acessar registros de rastreamento no dispositivo

Após o sistema criar o registro de rastreamento no dispositivo, você poderá acessar o arquivo de uma das seguintes formas:

  • Use o Device Explorer. Para abrir esse recurso, clique em View > Tool Windows > Device Explorer ou clique no botão Device Explorer na barra da janela de ferramentas. Como mostrado na Figura 1, você pode localizar os arquivos .trace navegando até o diretório específico do pacote do app.

    Figura 1. Localização dos registros de rastreamento usando o Device Explorer.

  • Copie o arquivo para a máquina local usando o comando adb pull. O comando abaixo copia um registro de rastreamento denominado sample.trace do dispositivo para o diretório ~/Documents/trace-logs/ da máquina local.

    adb pull path-on-device/sample.trace ~/Documents/trace-logs/

Em seguida, você pode importar o arquivo de rastreamento com o CPU Profiler.