Rastreamento no processo

A partir do Tracing 2.0, a biblioteca androidx.tracing oferece uma API Kotlin de baixa sobrecarga que permite capturar eventos de rastro em processo. Esses eventos podem capturar frações de tempo e o contexto delas. A biblioteca também é compatível com a propagação de contexto para corrotinas do Kotlin.

A biblioteca usa o mesmo formato de pacote de trace do Perfetto que os desenvolvedores Android já conhecem. Além disso, o Tracing 2.0 (ao contrário das APIs 1.0.0-*) oferece suporte à noção de back-ends de rastreamento conectáveis e coletores. Assim, outras bibliotecas de rastreamento podem personalizar o formato de rastreamento de saída e como a propagação de contexto funciona na implementação delas.

Dependências

Para iniciar o rastreamento, é necessário definir as dependências no build.gradle.kts.

Projetos Kotlin Multiplatform

As bibliotecas que só precisam emitir eventos de trace devem depender da API androidx.tracing:tracing, que é leve. Os apps que configuram o back-end de rastreamento também precisam depender de androidx.tracing:tracing-wire.

kotlin {
  sourceSets {
    commonMain {
      dependencies {
        // API definition
        implementation("androidx.tracing:tracing:2.0.5")
      }
    }
    androidMain {
      dependencies {
        // Android implementation (includes the Perfetto Sink and automatic initialization)
        implementation("androidx.tracing:tracing-wire:2.0.5")
      }
    }
    jvmMain {
      dependencies {
        // JVM implementation
        implementation("androidx.tracing:tracing-wire:2.0.5")
      }
    }
  }
}

Projetos somente para Android

Se você estiver segmentando apenas o Android, adicione o seguinte ao arquivo build.gradle.kts do aplicativo ou da biblioteca:

dependencies {
    // For libraries and applications to emit events
    implementation("androidx.tracing:tracing:2.0.5")

    // For applications to configure the tracing backend
    implementation("androidx.tracing:tracing-wire:2.0.5")
}

Inicialização e descoberta

Antes de registrar eventos de trace, é necessário inicializar a infraestrutura de rastreamento. Isso envolve criar um AbstractTraceDriver e registrar o Tracer dele globalmente.

Android

No Android, se você incluir a dependência androidx.tracing:tracing-wire, a inicialização vai acontecer automaticamente na inicialização do aplicativo usando a biblioteca androidx.startup.

Por padrão, essa inicialização automática faz o seguinte:

  • Cria um TraceDriver com um TraceSink que grava arquivos de rastreamento do Perfetto em Context.noBackupFilesDir/perfetto_traces/.

  • Registra o Tracer resultante globalmente.

Personalizar a instância TraceDriver

Se você precisar personalizar a configuração, por exemplo, para mudar onde os arquivos de rastreamento são salvos ou para usar um TraceSink personalizado, forneça sua própria instância de AbstractTraceDriver.

Para personalizar a configuração, faça com que a classe Application implemente AbstractTraceDriver.Factory:

import android.app.Application
import androidx.tracing.AbstractTraceDriver
import androidx.tracing.wire.TraceDriver
import androidx.tracing.wire.TraceSink
import java.io.File

class App : Application(), AbstractTraceDriver.Factory {
    override fun create(): AbstractTraceDriver {
        val sink = TraceSink(
            context = this,
            fileProvider = { File(noBackupFilesDir, "traces") },
        )
        // Return the custom TraceDriver
        // You can also fully customize the instance of Tracer
        return TraceDriver(context = this, sink = sink)
    }
}

O inicializador automático detecta que sua subclasse Application implementa Factory e usa sua fábrica de drivers personalizada.

JVM

Na JVM, não há um mecanismo de inicialização automática. O aplicativo é responsável por inicializar o TraceDriver e registrar o Tracer globalmente durante a inicialização, geralmente na função main.

Para registrar o rastreador, chame Tracer.setGlobalTracer().

import androidx.tracing.Tracer
import androidx.tracing.DelicateTracingApi
import androidx.tracing.wire.TraceDriver
import androidx.tracing.wire.TraceSink
import java.io.File

fun main() {
    // Create the TraceSink, and the `TraceDriver`
    val outputDirectory = File("/tmp/perfetto")
    val sink = TraceSink(directory = outputDirectory)
    val driver = TraceDriver(sink = sink, isEnabled = true)

    // Register the tracer
    @OptIn(DelicateTracingApi::class)
    Tracer.setGlobalTracer(driver.tracer)

    // Call driver.close() as a result of the process shutdown hook.
    Runtime.getRuntime().addShutdownHook(Thread {
        driver.close()
    })
}

Uso básico

Um TraceSink define como os pacotes de trace são serializados. O Tracing 2.0 vem com uma implementação de um coletor que usa o formato de pacote de trace Perfetto. Um TraceDriver fornece um identificador para o Tracer e pode ser usado para finalizar um trace.

Depois que o Tracer for inicializado, de forma automática no Android ou manual na JVM, use a instância global Tracer.global para emitir eventos de trace.

Também é possível usar o TraceDriver para desativar todos os pontos de trace no aplicativo, se você optar por não fazer nenhum trace em algumas variantes do aplicativo. É possível ativar pontos de trace para um determinado category fornecendo uma implementação para isCategoryEnabled ao criar uma instância de TraceDriver.

val driver = TraceDriver(
    sink = sink,
    isCategoryEnabled = { category ->
        // Only enable trace points in the "com.example" package
        category.startsWith("com.example")
    }
)

Veja um exemplo básico de como emitir um evento de trace usando Tracer.global na JVM, incluindo a configuração manual:

import androidx.tracing.Tracer
import androidx.tracing.DelicateTracingApi
import androidx.tracing.wire.TraceDriver
import androidx.tracing.wire.TraceSink
import java.io.File

// Category names should also follow the same convention used for package names
// on Android and Java. This makes them easier to identify and filter.
internal const val CATEGORY_MAIN = "com.example"

fun createSink(): TraceSink {
    val outputDirectory = File("/tmp/perfetto")
    if (!outputDirectory.exists()) {
        outputDirectory.mkdirs()
    }
    return TraceSink(directory = outputDirectory)
}

fun createTraceDriver(): TraceDriver {
    return TraceDriver(sink = createSink(), isCategoryEnabled = {true})
}

fun main() {
    val driver = createTraceDriver()
    @OptIn(DelicateTracingApi::class)
    Tracer.setGlobalTracer(driver.tracer)

    driver.use {
        Tracer.global.trace(category = CATEGORY_MAIN, name = "basic") {
            // The block of code that needs to be traced.
            Thread.sleep(100L)
        }
    }
}

Isso gera o seguinte trace.

Captura de tela de um rastro básico do Perfetto

Figura 1. Captura de tela de um rastro básico do Perfetto.

É possível notar que as faixas corretas de processo e linha de execução estão preenchidas e que elas produziram uma única seção de rastro basic, que foi executada por 100 ms.

As seções (ou fatias) de trace podem ser aninhadas na mesma faixa para representar eventos sobrepostos. Veja um exemplo.

fun main() {
    val driver = createTraceDriver()
    @OptIn(DelicateTracingApi::class)
    Tracer.setGlobalTracer(driver.tracer)

    driver.use {
        Tracer.global.trace(
            category = CATEGORY_MAIN,
            name = "processImage",
        ) {
            // Load the data first, then apply the sharpen filter
            sharpen(output = loadImage())
        }
    }
}

internal fun loadImage(): ByteArray {
    return Tracer.global.trace(CATEGORY_MAIN, "loadImage") {
        // Loads an image
        // ...
        // A placeholder
        ByteArray(0)
    }
}

internal fun sharpen(output: ByteArray) {
    // ...
    Tracer.global.trace(CATEGORY_MAIN, "sharpen") {
        // ...
    }
}

Isso gera o seguinte trace.

Captura de tela de um rastro básico do Perfetto com seções aninhadas

Figura 2. Captura de tela de um rastro básico do Perfetto com seções aninhadas.

É possível ver que há eventos sobrepostos na faixa da linha de execução principal. É muito claro que processImage chama loadImage e sharpen na mesma linha de execução.

Adicionar mais metadados em seções de trace

Às vezes, pode ser útil anexar mais metadados contextuais a uma fração de trace para receber mais detalhes. Alguns exemplos desses metadados podem incluir o nav destination em que o usuário está ou o input arguments que pode acabar determinando quanto tempo uma função leva.

fun main() {
    val driver = createTraceDriver()
    @OptIn(DelicateTracingApi::class)
    Tracer.setGlobalTracer(driver.tracer)

    driver.use {
        Tracer.global.trace(
            category = CATEGORY_MAIN,
            name = "basicWithContext",
            // Add additional metadata
            metadataBlock = {
                // Add key value pairs.
                addMetadataEntry("key", "value")
                addMetadataEntry("count", 1L)
            }
        ) {
            Thread.sleep(100L)
        }
    }
}

Isso produz o resultado a seguir. A seção Arguments contém pares de chave-valor adicionados ao produzir o slice.

Captura de tela de um trace básico do Perfetto com metadados adicionais

Figura 3. Captura de tela de um trace básico do Perfetto com metadados adicionais.

Propagação de contexto

Ao usar corrotinas do Kotlin ou outros frameworks semelhantes que ajudam com cargas de trabalho simultâneas, o Tracing 2.0 é compatível com a noção de propagação de contexto. A melhor forma de explicar isso é com um exemplo.

suspend fun taskOne() {
    Tracer.global.traceCoroutine(category = CATEGORY_MAIN, "taskOne") {
        delay(timeMillis = 100L)
    }
}

suspend fun taskTwo() {
    Tracer.global.traceCoroutine(category = CATEGORY_MAIN, "taskTwo") {
        delay(timeMillis = 50L)
    }
}

fun main() = runBlocking(context = Dispatchers.Default) {
    val driver = createTraceDriver()
    @OptIn(DelicateTracingApi::class)
    Tracer.setGlobalTracer(driver.tracer)

    driver.use {
        Tracer.global.traceCoroutine(category = CATEGORY_MAIN, name = "main") {
              taskOne()
              taskTwo()
            }
        }
        println("All done")
    }
}

Isso produz o resultado a seguir.

Captura de tela de um trace do Perfetto com propagação de contexto

Figura 4. Captura de tela de um trace básico do Perfetto com propagação de contexto.

A propagação de contexto simplifica bastante a visualização do fluxo de execução. É possível ver exatamente quais tarefas estavam relacionadas (conectadas a outras) e exatamente quando Threads foram suspensas e retomadas.

Por exemplo, é possível ver que a fração main gerou taskOne e taskTwo. Depois disso, as duas linhas de execução ficaram inativas porque as corrotinas foram suspensas devido ao uso de delay.

Propagação manual

Às vezes, ao misturar cargas de trabalho simultâneas usando corrotinas do Kotlin com instâncias de Executor do Java, pode ser útil propagar o contexto de uma para outra. Confira um exemplo:

fun executorTask(
    token: PropagationToken,
    executor: Executor,
    callback: () -> Unit
) {
    executor.execute {
        Tracer.global.trace(
            category = CATEGORY_MAIN,
            name = "executeTask",
            token = token,
        ) {
            // Do something
            Thread.sleep(100)
            callback()
        }
    }
}

fun main() = runBlocking(context = Dispatchers.Default) {
    val driver = createTraceDriver()
    @OptIn(DelicateTracingApi::class)
    Tracer.setGlobalTracer(driver.tracer)

    val executor = Executors.newSingleThreadExecutor()
    driver.use {
        Tracer.global.traceCoroutine(category = CATEGORY_MAIN, name = "main") {
            coroutineScope {
                val deferred = CompletableDeferred<Unit>()
                executorTask(
                    // Obtain the propagation token from the CoroutineContext
                    token = Tracer.global.tokenFromCoroutineContext(),
                    executor = executor,
                    callback = {
                        deferred.complete(Unit)
                    }
                )
                deferred.await()
            }
        }
        executor.shutdownNow()
    }
}

Isso produz o resultado a seguir.

Captura de tela de um trace do Perfetto com propagação de contexto manual

Figura 5. Captura de tela de um trace básico do Perfetto com propagação de contexto manual.

É possível notar que a execução começou em um CoroutineContext e, em seguida, mudou para um Executor do Java, mas ainda foi possível usar a propagação de contexto.

Combinar com rastreamentos do sistema

A biblioteca androidx.tracing não captura informações como programação de CPU, uso da memória e interação do aplicativo com o sistema operacional em geral. Isso ocorre porque a biblioteca oferece uma maneira de realizar rastreamento em processo de baixa sobrecarga.

No entanto, é extremamente simples mesclar rastreamentos do sistema com rastreamentos em processo e visualizá-los como um único rastreamento, se necessário. Isso ocorre porque o Perfetto UI permite visualizar vários arquivos de rastreamento de um dispositivo em uma linha do tempo unificada.

Para fazer isso, inicie uma sessão de rastreamento do sistema usando Perfetto UI e seguindo as instruções aqui.

Também é possível registrar eventos de rastreamento em processo usando a API Tracing 2.0 enquanto o rastreamento do sistema está ativado. Depois de ter ambos os arquivos de rastreamento, use a opção Open Multiple Trace Files no Perfetto.

Como abrir vários arquivos de rastreamento na interface do Perfetto

Figura 6. Abrir vários arquivos de rastreamento na interface do Perfetto.

Fluxos de trabalho avançados

Nesta seção, descrevemos fluxos de trabalho avançados que podem ser implementados com a biblioteca de rastreamento em processo.

Correlacionar fatias

Às vezes, é útil atribuir fatias em um rastro a uma ação do usuário de nível mais alto ou a um evento do sistema. Por exemplo, para atribuir todas as frações que correspondem a algum trabalho em segundo plano como parte de uma notificação, você pode fazer algo como:

fun main() {
    val driver = createTraceDriver()
    @OptIn(DelicateTracingApi::class)
    Tracer.setGlobalTracer(driver.tracer)

    driver.use {
        onEvent(eventId = EVENT_ID)
    }
}

fun onEvent(eventId: Long) {
    Tracer.global.trace(
        category = CATEGORY_MAIN,
        name = "step-1",
        metadataBlock = {
            addCorrelationId(eventId)
        }
    ) {
        Thread.sleep(100L)
    }

    Thread.sleep(20)

    Tracer.global.trace(
        category = CATEGORY_MAIN,
        name = "step-2",
        metadataBlock = {
            addCorrelationId(eventId)
        }
    ) {
        Thread.sleep(180)
    }
}

Isso produz o resultado a seguir.

Captura de tela de um rastro do Perfetto com frações correlacionadas

Figura 7. Captura de tela de um rastro do Perfetto com frações correlacionadas.

Adicionar informações da pilha de chamadas

As ferramentas do lado do host, como plug-ins de compilador e processadores de anotações, também podem incorporar informações da pilha de chamadas em um rastro para facilitar a localização do arquivo, da classe ou do método responsável por produzir uma seção de rastro em um rastro.

fun main() {
    val driver = createTraceDriver()
    @OptIn(DelicateTracingApi::class)
    Tracer.setGlobalTracer(driver.tracer)

    driver.use {
        Tracer.global.trace(
            category = CATEGORY_MAIN,
            name = "callStackEntry",
            metadataBlock = {
                addCallStackEntry(
                    name = "main",
                    lineNumber = 14,
                    sourceFile = "Basic.kt"
                )
            }
        ) {
            Thread.sleep(100L)
        }
    }
}

Isso produz o resultado a seguir.

Captura de tela de um rastro do Perfetto com informações da pilha de chamadas

Figura 8. Captura de tela de um rastro do Perfetto com informações da pilha de chamadas.