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

Para gerar um rastreamento de método na execução de um aplicativo, você pode instrumentar esse aplicativo usando a classe Debug. A instrumentação do aplicativo 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. Em seguida, 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 aplicativo.

Antes de começar a gerar registros de rastreamento, verifique se o aplicativo tem permissão para gravar no armazenamento externo (WRITE_EXTERNAL_STORAGE) para poder salvar os registros de rastreamento no dispositivo.

Instrumentar o aplicativo

Para criar registros de rastreamento, chame startMethodTracing() quando 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 aplicativo, 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 encadeamentos 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 aplicativo chamar startMethodTracing() novamente sem alterar o nome do registro de rastreamento, o registro existente salvo no dispositivo será substituído. Para saber como alterar dinamicamente o nome de cada registro de rastreamento, vá para a seção sobre salvar vários registros.

Se o sistema alcançar o tamanho máximo do buffer antes da chamada de stopMethodTracing(), ele 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 aplicativo. 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 aplicativo executará 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 executar"). 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 alterações recentes aumentaram ou reduziram o desempenho do aplicativo.

Ao implantar em dispositivos executando o Android 5.0 (API de nível 21) ou versões posteriores, você poderá 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 de amostra, chame startMethodTracingSampling() (em vez de chamar startMethodTracing()) com um intervalo de amostragem especificado. O sistema coleta periodicamente as amostras até que o aplicativo chame stopMethodTracing().

Salvar vários registros

Se o aplicativo 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, somente o registro de rastreamento mais recente é mantido. Para salvar vários registros de rastreamento no dispositivo, renomeie dinamicamente o registro de rastreamento a cada vez que o aplicativo 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

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

  • Use o Device File Explorer. Para abri-lo, clique em View > Tool Windows > Device File Explorer (ou clique no botão Device File Explorer na barra da janela de ferramentas). Como mostrado na figura 1, você pode localizar os arquivos .trace navegando para o diretório específico do pacote do aplicativo.

    Figura 1. Localização dos registros de rastreamento usando o Device File 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.