Criação de perfil orientada por apps

No Android 15 (nível 35 da API) e versões mais recentes, a criação de perfil orientada por app permite que o app inicie e interrompa explicitamente as gravações de perfil compatíveis no código usando a API ProfilingManager ou os builders do AndroidX Core (androidx.core:core 1.15.0 ou mais recente). Use a criação de perfil direta quando quiser controlar o tempo do perfil ou os parâmetros da sessão, como durações, políticas de buffer e taxas de amostragem, ou segmentar uma jornada do usuário ou condição de execução específica.

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-ktx:2.0.5")
       implementation("androidx.core:core:1.19.1")
   }
   

Groovy

   dependencies {
       implementation 'androidx.tracing:tracing-ktx:2.0.5'
       implementation 'androidx.core:core:1.19.1'
   }
   

Registrar um rastro do sistema

Depois de adicionar as dependências necessárias, use o código abaixo para registrar um rastreamento do sistema. Este exemplo mostra como iniciar uma sessão de criação de perfil enquanto gerencia com segurança operações pesadas fora da linha de execução principal.

Kotlin

@RequiresApi(Build.VERSION_CODES.VANILLA_ICE_CREAM)
@Composable
fun ProfiledScreen(modifier: Modifier = Modifier) {
    // Use the application context: requestProfiling resolves the ProfilingManager
    // system service from it, so there's no reason to hand it a short-lived Activity.
    val appContext = LocalContext.current.applicationContext
    val scope = rememberCoroutineScope()

    Button(
        onClick = {
            // Run the orchestration off the main thread. Profiling a heavy operation
            // on the UI thread would freeze the UI (ANR) and distort the very metrics
            // you're trying to capture.
            //
            // Note: this scope is tied to composition. If the user leaves this screen
            // mid-session, the coroutine is cancelled and stopSignal.cancel() might not
            // run, but setDurationMs() acts as a safety net and ends the profile.
            scope.launch(Dispatchers.Default) {
                val callbackExecutor = Dispatchers.IO.asExecutor()
                val resultCallback = Consumer<ProfilingResult> { profilingResult ->
                    if (profilingResult.errorCode == ProfilingResult.ERROR_NONE) {
                        Log.d("ProfileTest", "Result file: ${profilingResult.resultFilePath}")
                    } else {
                        // errorMessage explains the failure (e.g., rate limiting); keep it.
                        Log.e(
                            "ProfileTest",
                            "Profiling failed errorCode=${profilingResult.errorCode} " +
                                "errorMessage=${profilingResult.errorMessage}"
                        )
                    }
                }

                val stopSignal = CancellationSignal()
                val requestBuilder = SystemTraceRequestBuilder().apply {
                    setCancellationSignal(stopSignal)
                    setTag("FOO") // Caller-supplied tag for identification.
                    setDurationMs(60000) // Hard cap: ends the session if cancel() never fires.
                    setBufferFillPolicy(BufferFillPolicy.RING_BUFFER)
                    setBufferSizeKb(32768)
                }

                // 1. Start the session. This is asynchronous system IPC. The tracing
                //    engine takes a moment to start and allocate buffers.
                requestProfiling(appContext, requestBuilder.build(), callbackExecutor, resultCallback)

                // 2. The API exposes no "profiling started" signal, so pad with a short,
                //    best-effort delay before running the code you care about. This is
                //    approximate. Increase it on slower or heavily loaded devices.
                delay(STARTUP_PADDING_MS)

                // 3. The session is already recording every thread in your app. This slice
                //    doesn't scope what's captured. It just labels this region of the
                //    timeline so heavyOperation() is easier to find. trace { } closes the
                //    section even if the block throws.

                trace("MyApp:HeavyOperation") {
                    heavyOperation()
                }

                // 4. Stop recording. Until this fires or the setDurationMs() cap is
                //    reached (whichever comes first), the session keeps capturing app-wide
                //    activity.

                stopSignal.cancel()
            }
        }
    ) {
        Text("Run & Profile Heavy Operation")
    }
}

// Best-effort wait for the system trace engine to initialize before profiling.
// There is no deterministic start callback; tune this for your target devices.
private const val STARTUP_PADDING_MS = 100L

fun heavyOperation() {
    // Background computations to profile.
}

Java

void sampleRecordSystemTrace(Context context) {
  // Use the application context: requestProfiling resolves the ProfilingManager
  // system service from it, so there's no reason to hand it a short-lived Activity.
  Context appContext = context.getApplicationContext();

  // Run the orchestration off the main thread. Profiling a heavy operation
  // on the UI thread would freeze the UI (ANR) and distort the very metrics
  // you're trying to capture.
  profilingExecutor.execute(() -> {
    Executor callbackExecutor = Executors.newSingleThreadExecutor();
    Consumer<ProfilingResult> resultCallback = profilingResult -> {
      if (profilingResult.getErrorCode() == ProfilingResult.ERROR_NONE) {
        Log.d("ProfileTest", "Result file: " + profilingResult.getResultFilePath());
      } else {
        // errorMessage explains the failure (e.g., rate limiting); keep it.
        Log.e(
            "ProfileTest",
            "Profiling failed errorCode=" + profilingResult.getErrorCode()
                + " errorMessage=" + profilingResult.getErrorMessage());
      }
    };

    CancellationSignal stopSignal = new CancellationSignal();
    SystemTraceRequestBuilder requestBuilder = new SystemTraceRequestBuilder();
    requestBuilder.setCancellationSignal(stopSignal);
    requestBuilder.setTag("FOO"); // Caller-supplied tag for identification.
    requestBuilder.setDurationMs(60000); // Hard cap: ends the session if cancel() never fires.
    requestBuilder.setBufferFillPolicy(BufferFillPolicy.RING_BUFFER);
    requestBuilder.setBufferSizeKb(32768);

    // 1. Start the session. This is asynchronous system IPC. The tracing
    //    engine takes a moment to start and allocate buffers.
    Profiling.requestProfiling(
        appContext, requestBuilder.build(), callbackExecutor, resultCallback);

    // 2. The API exposes no "profiling started" signal, so pad with a short,
    //    best-effort delay before running the code you care about. This is
    //    approximate. Increase it on slower or heavily loaded devices.
    try {
      Thread.sleep(STARTUP_PADDING_MS);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      stopSignal.cancel();
      return;
    }

    // 3. The session is already recording every thread in your app. This slice
    //    doesn't scope what's captured. It just labels this region of the
    //    timeline so heavyOperation() is easier to find. try/finally closes the
    //    section even if heavyOperation() throws.
    Trace.beginSection("MyApp:HeavyOperation");
    try {
      heavyOperation();
    } finally {
      Trace.endSection();
    }

    // 4. Stop recording. Until this fires or the setDurationMs() cap is
    //    reached (whichever comes first), the session keeps capturing app-wide
    //    activity.
    stopSignal.cancel();
  });
}

// Best-effort wait for the system trace engine to initialize before profiling.
// There is no deterministic start callback; tune this for your target devices.
private static final long STARTUP_PADDING_MS = 100L;

// Single background thread that runs the profiling orchestration.
private final ExecutorService profilingExecutor = Executors.newSingleThreadExecutor();

void heavyOperation() {
  // Background computations to profile.
}

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

  1. Configurar o executor: crie um Executor que não seja de IU para receber resultados de criação de perfil fora da linha de execução principal.
  2. Processar resultados de criação de perfil: crie um callback Consumer<ProfilingResult> para receber o resultado concluído ou o erro de ProfilingManager.
  3. Crie a solicitação de criação de perfil: crie um SystemTraceRequestBuilder para personalizar as configurações da sessão (ou omita as personalizações para usar os padrões do sistema):

    • setTag(): anexa uma tag fornecida pelo autor da chamada que é retornada por ProfilingResult.getTag e adicionada ao final do nome do arquivo de saída (até os primeiros 20 caracteres alfanuméricos minúsculos e hifens).
    • setDurationMs(): define a duração máxima da gravação em milissegundos (por exemplo, 60000 para 60 segundos).
    • setBufferFillPolicy(): define como o buffer lida com os limites de capacidade: BufferFillPolicy.RING_BUFFER substitui os dados mais antigos quando está cheio, enquanto BufferFillPolicy.DISCARD para de gravar novos dados quando o buffer está cheio.
    • setBufferSizeKb(): define o tamanho do buffer de gravação em kilobytes.
  4. Opcional: interromper a gravação antes do tempo: transmita um CancellationSignal (stopSignal) para interromper a sessão assim que a operação de destino for concluída, salvando os dados gravados até o momento e entregando o ProfilingResult ao seu callback. Consulte Interromper uma gravação ativa para mais detalhes.

  5. Iniciar e receber resultados: chame requestProfiling() para iniciar a gravação em segundo plano. Quando a sessão termina, resultCallback.accept() recebe um ProfilingResult:

    • Em caso de sucesso (ERROR_NONE), chame getResultFilePath() para receber o caminho no dispositivo. Para instruções sobre como extrair arquivos com adb ou fazer upload deles com WorkManager, consulte Recuperar e fazer upload de perfis.
    • Em caso de falha, inspecione getErrorCode() e getErrorMessage(). As solicitações podem falhar devido à limitação de taxa, além de vários outros motivos.
    • Se o app for encerrado antes que o resultado seja entregue, o sistema vai colocar o resultado em fila e o entregará na próxima vez que o app registrar um listener global com registerForAllProfilingResults.
  6. Adicionar pontos de rastreamento personalizados: envolva as operações em trace("...") { ... } (ou Trace.beginSection() / Trace.endSection()) para rotular regiões da linha do tempo.

Interromper uma gravação ativa

Para interromper uma captura assim que uma interação for concluída, em vez de esperar que setDurationMs() expire, transmita um CancellationSignal para setCancellationSignal() ou requestProfiling(). Se você especificar CancellationSignal e setDurationMs(), o que acontecer primeiro vai encerrar a sessão. Se você não especificar nenhum, o sistema vai aplicar uma duração padrão.

Ligar para cancel() não descarta a gravação. O sistema interrompe a captura, encobre e salva os dados coletados até aquele momento e entrega o ProfilingResult ao listener com ERROR_NONE.

Registrar rastreamentos do sistema com amostragem de pilha de chamadas

Em dispositivos com o Android 17 (nível 37 da API) e versões mais recentes (ou Android 16 com um módulo principal Profiling atualizado), o ProfilingManager oferece suporte à coleta de pilhas de chamadas de amostra com um rastreamento do sistema em uma única sessão para que você possa ver eventos da linha do tempo, como estados de linha de execução, frames e fatias de rastreamento personalizadas, além de pilhas de chamadas de CPU para métodos sem instrumentação de rastreamento explícita.

Este exemplo também mostra como chamar ProfilingManager.requestProfiling diretamente sem os builders do Jetpack, especificando um dos tipos de perfil compatíveis (PROFILING_TYPE_SYSTEM_TRACE) e transmitindo uma configuração Bundle:

Kotlin

val profilingManager = context.getSystemService(ProfilingManager::class.java)

// Pass a Bundle to customize the capture, or pass null for default settings.
val config = Bundle().apply {
    putInt("KEY_DURATION_MS", 15000) // 15 seconds
    putInt("KEY_SIZE_KB", 20480) // 20 MB buffer size

    // Collect sampled CPU call stacks alongside the system trace.
    putBoolean("KEY_COLLECT_STACK_SAMPLING", true)
    putInt("KEY_FREQUENCY_HZ", 100) // Sampling frequency in Hz
    // Optional: Set KEY_SAMPLE_BINDER_ONLY to true to sample only binder calls.
}
profilingManager?.requestProfiling(
    ProfilingManager.PROFILING_TYPE_SYSTEM_TRACE,
    config,
    "trace-with-callstacks",
    null,
    callbackExecutor,
    resultCallback
)

Java

ProfilingManager profilingManager = context.getSystemService(ProfilingManager.class);
if (profilingManager == null) return;

// Pass a Bundle to customize the capture, or pass null for default settings.
Bundle config = new Bundle();
config.putInt("KEY_DURATION_MS", 15000); // 15 seconds
config.putInt("KEY_SIZE_KB", 20480); // 20 MB buffer size

// Collect sampled CPU call stacks alongside the system trace.
config.putBoolean("KEY_COLLECT_STACK_SAMPLING", true);
config.putInt("KEY_FREQUENCY_HZ", 100); // Sampling frequency in Hz
// Optional: Set KEY_SAMPLE_BINDER_ONLY to true to sample only binder calls.

profilingManager.requestProfiling(
    ProfilingManager.PROFILING_TYPE_SYSTEM_TRACE,
    config,
    "trace-with-callstacks",
    null,
    callbackExecutor,
    resultCallback
);

Quando você abre o perfil resultante na interface do Perfetto, as pilhas de chamadas amostradas aparecem como faixas dedicadas de pilhas de chamadas ao lado das frações de rastro regulares do app. Selecione uma região de uma faixa de pilha de chamadas para ver um gráfico de chama das pilhas de chamadas de amostra para esse período, como mostrado na Figura 1.

Interface do Perfetto mostrando um rastreamento do sistema com faixas de pilha de chamadas de amostra, frações de rastreamento
  no RenderThread e um gráfico de chama da pilha de chamadas para a área
  selecionada.
Figura 1. Um rastreamento do sistema combinado com a amostragem de pilha de chamadas na interface do Perfetto.

Capturar um heap dump do Java

É possível solicitar um snapshot da memória Java do app usando JavaHeapDumpRequestBuilder (ou PROFILING_TYPE_JAVA_HEAP_DUMP). Ao contrário dos heap dumps padrão de .hprof capturados com Debug.dumpHprofData, os heap dumps de ProfilingManager são projetados para coleta segura e de baixa sobrecarga em produção:

  • Coleta sem congelamento: o sistema bifurca um clone de cópia em gravação do processo do app e coleta o instantâneo de alocação heap do processo clonado para que o app não congele enquanto o despejo é gravado no disco.
  • Somente gráfico de referência (sem dados de objeto brutos): em vez de despejar o conteúdo bruto da memória, como um arquivo .hprof, o ProfilingManager registra um gráfico de protobuf .perfetto-java-heap-dump que contém classes, tamanhos de objetos, cadeias de referência e raízes de coleta de lixo (GC, na sigla em inglês), omitindo valores primitivos, conteúdo de string e payloads de matriz. Isso protege a privacidade do usuário e reduz o tamanho do arquivo. Para uma análise completa, consulte Como os heap dumps do ProfilingManager são diferentes dos dumps do HPROF.

Usando a mesma configuração de Context, Executor e resultCallback mostrada em Registrar um rastreamento do sistema, crie uma solicitação com JavaHeapDumpRequestBuilder:

Kotlin

val heapDumpRequest = JavaHeapDumpRequestBuilder()
    .setTag("memory-leak-check")
    .build()

requestProfiling(
    appContext,
    heapDumpRequest,
    callbackExecutor,
    resultCallback
)

Java

ProfilingRequest heapDumpRequest = new JavaHeapDumpRequestBuilder()
    .setTag("memory-leak-check")
    .build();

Profiling.requestProfiling(
    getApplicationContext(),
    heapDumpRequest,
    callbackExecutor,
    resultCallback
);

Para um tutorial completo de análise de um heap dump do Java para diagnosticar um vazamento de memória, consulte Estudo de caso: depurar uma falha de OOM.

Próximas etapas

Depois de capturar os perfis, recupere-os localmente com adb ou faça upload deles para o back-end com WorkManager.