Seguimiento en proceso

A partir de Tracing 2.0, la biblioteca androidx.tracing proporciona una API de Kotlin de baja sobrecarga que te permite capturar eventos de seguimiento en proceso. Estos eventos pueden capturar fragmentos de tiempo y su contexto. La biblioteca también admite la propagación de contexto para las corrutinas de Kotlin.

La biblioteca usa el mismo formato de paquete de seguimiento de Perfetto con el que están familiarizados los desarrolladores de Android. Además, Tracing 2.0 (a diferencia de las APIs de 1.0.0-*) admite la noción de backends de seguimiento conectables y receptores, por lo que otras bibliotecas de seguimiento pueden personalizar el formato de seguimiento de salida y cómo funciona la propagación de contexto en su implementación.

Dependencias

Para comenzar a realizar el seguimiento, debes definir las dependencias en tu build.gradle.kts.

Proyectos de Kotlin Multiplatform

Las bibliotecas que solo necesitan emitir eventos de seguimiento deben depender de la API de androidx.tracing:tracing ligera. Las apps que configuran el backend de seguimiento también deben 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")
      }
    }
  }
}

Proyectos solo para Android

Si solo te orientas a Android, agrega lo siguiente al archivo build.gradle.kts de tu aplicación o 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")
}

Inicialización y descubrimiento

Antes de poder registrar eventos de seguimiento, debes inicializar la infraestructura de seguimiento. Esto implica crear un AbstractTraceDriver y registrar su Tracer de forma global.

Android

En Android, si incluyes la dependencia androidx.tracing:tracing-wire, la inicialización se produce automáticamente cuando se inicia la aplicación con la biblioteca androidx.startup.

De forma predeterminada, esta inicialización automática hace lo siguiente:

  • Crea un TraceDriver con un TraceSink que escribe archivos de registro de Perfetto en Context.noBackupFilesDir/perfetto_traces/.

  • Registra el Tracer resultante de forma global.

Personaliza la instancia de TraceDriver

Si necesitas personalizar la configuración, por ejemplo, para cambiar dónde se guardan los archivos de registro o usar un TraceSink personalizado, puedes proporcionar tu propia instancia de AbstractTraceDriver.

Para personalizar la configuración, haz que tu clase 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)
    }
}

El inicializador automático detecta que tu subclase Application implementa Factory y usa tu fábrica de controladores personalizada.

JVM

En la JVM, no hay un mecanismo de arranque automático. La aplicación es responsable de inicializar el TraceDriver y registrar el Tracer de forma global durante el inicio, por lo general, en tu función main.

Para registrar el rastreador, llama a 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

Un TraceSink define cómo se serializan los paquetes de seguimiento. La versión 2.0 de Tracing incluye una implementación de un receptor que usa el formato de paquete de seguimiento Perfetto. Un TraceDriver proporciona un controlador para el Tracer y se puede usar para finalizar un seguimiento.

Una vez que se inicializa Tracer, ya sea de forma automática en Android o de forma manual en la JVM, usa la instancia global Tracer.global para emitir eventos de seguimiento.

También puedes usar TraceDriver para inhabilitar todos los puntos de seguimiento en la aplicación si decides no realizar ningún seguimiento en algunas variantes de la aplicación. De manera opcional, puedes habilitar puntos de seguimiento para un category determinado proporcionando una implementación para isCategoryEnabled cuando crees una instancia de TraceDriver.

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

Este es un ejemplo básico de cómo emitir un evento de seguimiento con Tracer.global en la JVM, incluida la configuración 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)
        }
    }
}

Esto genera el siguiente seguimiento.

Captura de pantalla de un registro básico de Perfetto

Figura 1: Captura de pantalla de un registro básico de Perfetto.

Puedes ver que se propagan las pistas correctas de procesos y subprocesos, y que produjeron una sola sección de registro basic, que se ejecutó durante 100 ms.

Las secciones de seguimiento (o porciones) se pueden anidar en la misma pista para representar eventos superpuestos. A continuación, se muestra un ejemplo.

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") {
        // ...
    }
}

Esto genera el siguiente seguimiento.

Captura de pantalla de un registro básico de Perfetto con secciones anidadas

Figura 2: Captura de pantalla de un registro básico de Perfetto con secciones anidadas

Puedes ver que hay eventos superpuestos en la pista del subproceso principal. Está muy claro que processImage llama a loadImage y sharpen en el mismo subproceso.

Agrega metadatos adicionales en las secciones de seguimiento

A veces, puede ser útil adjuntar metadatos contextuales adicionales a un segmento de seguimiento para obtener más detalles. Algunos ejemplos de estos metadatos podrían incluir el nav destination en el que se encuentra el usuario o input arguments que podría terminar determinando cuánto tiempo tarda una función.

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)
        }
    }
}

Esto produce el siguiente resultado. Ten en cuenta que la sección Arguments contiene pares clave-valor que se agregaron cuando se produjo el slice.

Captura de pantalla de un registro básico de Perfetto con metadatos adicionales

Figura 3: Captura de pantalla de un registro básico de Perfetto con metadatos adicionales

Propagación del contexto

Cuando se usan corrutinas de Kotlin o algún otro framework similar que ayude con las cargas de trabajo simultáneas, Tracing 2.0 admite la noción de propagación de contexto. Esto se explica mejor con un ejemplo.

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")
    }
}

Esto produce el siguiente resultado.

Captura de pantalla de un registro de Perfetto con propagación de contexto

Figura 4: Captura de pantalla de un registro básico de Perfetto con propagación de contexto

La propagación de contexto hace que sea mucho más sencillo visualizar el flujo de ejecución. Puedes ver exactamente qué tareas estaban relacionadas (conectadas a otras) y exactamente cuándo se suspendieron y reanudaron las Threads.

Por ejemplo, puedes ver que el segmento main generó taskOne y taskTwo. Después de eso, ambos subprocesos estuvieron inactivos porque las corrutinas se suspendieron debido al uso de delay.

Propagación manual

A veces, cuando mezclas cargas de trabajo simultáneas con corrutinas de Kotlin con instancias de Executor de Java, puede ser útil propagar el contexto de una a otra. A continuación, se muestra un ejemplo:

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()
    }
}

Esto produce el siguiente resultado.

Captura de pantalla de un registro de Perfetto con propagación manual del contexto

Figura 5: Captura de pantalla de un registro básico de Perfetto con propagación manual del contexto

Puedes ver que la ejecución comenzó en un CoroutineContext y, luego, cambió a un Executor de Java, pero aún pudimos usar la propagación de contexto.

Combina con seguimientos del sistema

La biblioteca androidx.tracing no captura información como la programación de la CPU, el uso de memoria y la interacción de la aplicación con el sistema operativo en general. Esto se debe a que la biblioteca proporciona una forma de realizar un seguimiento en proceso con baja sobrecarga.

Sin embargo, es muy sencillo combinar los seguimientos del sistema con los seguimientos en proceso y visualizarlos como un solo seguimiento si es necesario. Esto se debe a que Perfetto UI admite la visualización de varios archivos de registro de un dispositivo en un cronograma unificado.

Para ello, puedes iniciar una sesión de registro del sistema con Perfetto UI siguiendo las instrucciones que se indican aquí.

También puedes registrar eventos de seguimiento en proceso con la API de Tracing 2.0 mientras el registro del sistema está activado. Una vez que tengas ambos archivos de registro, podrás usar la opción Open Multiple Trace Files en Perfetto.

Cómo abrir varios archivos de registro en la IU de Perfetto

Figura 6: Abre varios archivos de registro en la IU de Perfetto.

Flujos de trabajo avanzados

En esta sección, se describen los flujos de trabajo avanzados que puedes implementar con la biblioteca de seguimiento en proceso.

Correlaciona porciones

A veces, es útil atribuir porciones de un registro a una acción del usuario o un evento del sistema de nivel superior. Por ejemplo, para atribuir todos los segmentos que corresponden a un trabajo en segundo plano como parte de una notificación, puedes hacer lo siguiente:

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)
    }
}

Esto produce el siguiente resultado.

Captura de pantalla de un registro de Perfetto con porciones correlacionadas

Figura 7: Captura de pantalla de un registro de Perfetto con porciones correlacionadas

Agrega información de la pila de llamadas

Las herramientas del host, como los complementos del compilador y los procesadores de anotaciones, también pueden incorporar información de la pila de llamadas en un registro para que sea más fácil ubicar el archivo, la clase o el método responsable de producir una sección de registro en un registro.

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)
        }
    }
}

Esto produce el siguiente resultado.

Captura de pantalla de un registro de Perfetto con información de la pila de llamadas

Figura 8: Captura de pantalla de un registro de Perfetto con información de la pila de llamadas