Criação de perfil orientada por apps

Esta página mostra como registrar um rastro do sistema usando a API ProfilingManager.

O ProfilingManager também pode registrar outros tipos de perfil. Esse processo é semelhante ao registro de um rastro do sistema, mas cada tipo usa um builder diferente. Os perfis com suporte e os builders deles são:

  • Rastros do sistema:registrados usando SystemTraceRequestBuilder, que são úteis para análise de latência e depuração geral de desempenho.

  • Dumps de heap: registrados usando JavaHeapDumpRequestBuilder, que são úteis para detecção e otimização de vazamento de memória.

  • Perfis de heap: registrados usando HeapProfileRequestBuilder, que são úteis para otimização de memória.

  • Perfis de pilha de chamadas: registrados usando StackSamplingRequestBuilder, que são úteis para entender a execução do código e a análise de latência.

Adicionar dependências

Para ter a melhor experiência com a API ProfilingManager, adicione as seguintes bibliotecas do Jetpack ao arquivo build.gradle.kts.

Kotlin

   dependencies {
       implementation("androidx.tracing:tracing:1.3.0")
       implementation("androidx.core:core:1.18.0")
   }

Groovy

   dependencies {
       implementation 'androidx.tracing:tracing:1.3.0'
       implementation 'androidx.core:core:1.18.0'
   }

Registrar um rastro do sistema

Depois de adicionar as dependências necessárias, use o código a seguir para registrar um rastro do sistema. Este exemplo mostra uma configuração básica em uma Activity para iniciar e gerenciar uma sessão de criação de perfil.

Kotlin

@RequiresApi(Build.VERSION_CODES.VANILLA_ICE_CREAM)
fun sampleRecordSystemTrace() {
    val mainExecutor: Executor =
        Dispatchers.IO.asExecutor() // Your choice of executor for the callback to occur on.
    val resultCallback = Consumer<ProfilingResult> { profilingResult ->
        if (profilingResult.errorCode == ProfilingResult.ERROR_NONE) {
            Log.d(
                "ProfileTest",
                "Received profiling result file=" + profilingResult.resultFilePath
            )
        } else {
            Log.e(
                "ProfileTest",
                "Profiling failed errorcode=" + profilingResult.errorCode + " errormsg=" + profilingResult.errorMessage
            )
        }
    }
    val stopSignal = CancellationSignal()

    val requestBuilder = SystemTraceRequestBuilder()
    requestBuilder.setCancellationSignal(stopSignal)
    requestBuilder.setTag("FOO") // Caller supplied tag for identification
    requestBuilder.setDurationMs(60000)
    requestBuilder.setBufferFillPolicy(BufferFillPolicy.RING_BUFFER)
    requestBuilder.setBufferSizeKb(20971520)
    requestProfiling(applicationContext, requestBuilder.build(), mainExecutor, resultCallback)

    // Wait some time for profiling to start.

    Trace.beginSection("MyApp:HeavyOperation")
    heavyOperation()
    Trace.endSection()

    // Once the interesting code section is profiled, stop profile
    stopSignal.cancel()
}

fun heavyOperation() {
    // Computations you want to profile
}
ProfilingManagerKotlinSnippets.kt

Java

void heavyOperation() {
  // Computations you want to profile
}

void sampleRecordSystemTrace() {
  Executor mainExecutor = Executors.newSingleThreadExecutor();
  Consumer<ProfilingResult> resultCallback =
      new Consumer<ProfilingResult>() {
        @Override
        public void accept(ProfilingResult profilingResult) {
          if (profilingResult.getErrorCode() == ProfilingResult.ERROR_NONE) {
            Log.d(
                "ProfileTest",
                "Received profiling result file=" + profilingResult.getResultFilePath());
            setupProfileUploadWorker(profilingResult.getResultFilePath());
          } else {
            Log.e(
                "ProfileTest",
                "Profiling failed errorcode="

                    + profilingResult.getErrorCode()
                    + " errormsg="
                    + profilingResult.getErrorMessage());
          }
        }
      };
  CancellationSignal stopSignal = new CancellationSignal();

  SystemTraceRequestBuilder requestBuilder = new SystemTraceRequestBuilder();
  requestBuilder.setCancellationSignal(stopSignal);
  requestBuilder.setTag("FOO");
  requestBuilder.setDurationMs(60000);
  requestBuilder.setBufferFillPolicy(BufferFillPolicy.RING_BUFFER);
  requestBuilder.setBufferSizeKb(20971520);
  Profiling.requestProfiling(getApplicationContext(), requestBuilder.build(), mainExecutor,
      resultCallback);

  // Wait some time for profiling to start.

  Trace.beginSection("MyApp:HeavyOperation");
  heavyOperation();
  Trace.endSection();

  // Once the interesting code section is profiled, stop profile
  stopSignal.cancel();
}
ProfilingManagerJavaSnippets.java

O exemplo de código configura e gerencia a sessão de criação de perfil seguindo estas etapas:

  1. Configurar o executor. Crie um Executor para definir a linha de execução que vai receber os resultados da criação de perfil. A criação de perfil acontece em segundo plano. O uso de um executor de linha de execução que não seja da interface ajuda a evitar erros de "O app não está respondendo" (ANR) se você adicionar mais processamento ao callback mais tarde.

  2. Processar resultados da criação de perfil. Crie um objeto Consumer<ProfilingResult>. O sistema usa esse objeto para enviar os resultados da criação de perfil do ProfilingManager de volta ao seu app.

  3. Criar a solicitação de criação de perfil. Crie um SystemTraceRequestBuilder para configurar sua sessão de criação de perfil. Esse builder permite personalizar as configurações de rastreamento do ProfilingManager. A personalização do builder é opcional. Se você não fizer isso, o sistema vai usar as configurações padrão.

    • Definir uma tag. Use setTag() para adicionar uma tag ao nome do rastro. Essa tag ajuda a identificar o rastro.
    • Opcional: definir a duração. Use setDurationMs() para especificar por quanto tempo criar o perfil em milissegundos. Por exemplo, 60000 define um rastro de 60 segundos. O rastro termina automaticamente após a duração especificada se CancellationSignal não for acionado antes disso.
    • Escolher uma política de buffer. Use setBufferFillPolicy() para definir como os dados de rastreamento são armazenados. BufferFillPolicy.RING_BUFFER significa que, quando o buffer está cheio, os novos dados substituem os mais antigos, mantendo um registro contínuo da atividade recente.
    • Definir um tamanho de buffer. Use setBufferSizeKb() para especificar um tamanho de buffer para rastreamento, que pode ser usado para controlar o tamanho do arquivo de rastreamento de saída.

  4. Opcional: gerenciar o ciclo de vida da sessão. Crie um CancellationSignal. Esse objeto permite interromper a sessão de criação de perfil quando quiser, oferecendo controle preciso sobre a duração dela.

  5. Iniciar e receber resultados. Quando você chama requestProfiling(), o ProfilingManager inicia uma sessão de criação de perfil em segundo plano. Quando a criação de perfil é concluída, ela envia o ProfilingResult para o método resultCallback#accept. Se a criação de perfil for concluída, o ProfilingResult vai fornecer o caminho em que o rastro foi salvo no dispositivo usando ProfilingResult#getResultFilePath. É possível acessar esse arquivo de maneira programática ou, para criação de perfil local, executando adb pull <trace_path> no computador.

  6. Adicionar pontos de rastreamento personalizados. É possível adicionar pontos de rastreamento personalizados no código do app. No exemplo de código anterior, uma fatia de rastreamento chamada MyApp:HeavyOperation é adicionada usando Trace.beginSection() e Trace.endSection(). Essa fatia personalizada aparece no perfil gerado, destacando operações específicas no app.