进程内跟踪

从 Tracing 2.0 开始,androidx.tracing 库提供了一个低开销的 Kotlin API,可让您捕获进程内跟踪事件。这些事件可以捕获时间片及其上下文。该库还支持 Kotlin 协程的上下文传播。

该库使用 Android 开发者熟悉的 Perfetto 跟踪记录数据包格式。此外,Tracing 2.0(与 1.0.0-* API 不同)支持可插入式跟踪后端和接收器的概念,因此其他跟踪库可以自定义输出跟踪格式以及上下文传播在其实现中的工作方式。

依赖项

如需开始跟踪,您需要在 build.gradle.kts 中定义依赖项。

Kotlin Multiplatform 项目

只需发出跟踪事件的库应依赖于轻量级 androidx.tracing:tracing API。配置跟踪后端的应用也应依赖于 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")
      }
    }
  }
}

仅限 Android 的项目

如果您仅以 Android 为目标平台,请将以下内容添加到应用或库的 build.gradle.kts 文件中:

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

初始化和发现

您必须先初始化跟踪基础架构,然后才能记录跟踪事件。这涉及创建 AbstractTraceDriver 并全局注册其 Tracer。

Android

在 Android 上,如果您添加 androidx.tracing:tracing-wire 依赖项,则系统会在应用启动时使用 androidx.startup 库自动进行初始化。

默认情况下,此自动初始化会执行以下操作:

  • 创建一个 TraceDriver,其中包含一个将 Perfetto 跟踪文件写入 Context.noBackupFilesDir/perfetto_traces/ 的 TraceSink。

  • 全局注册生成的 Tracer。

自定义 TraceDriver 实例

如果您需要自定义配置(例如,更改跟踪文件的保存位置或使用自定义 TraceSink),则可以提供自己的 AbstractTraceDriver 实例。

如需自定义配置,请让您的 Application 类实现 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)
    }
}

自动初始化程序会检测到您的 Application 子类实现了 Factory,并使用您的自定义驱动程序工厂。

JVM

在 JVM 上,没有自动引导机制。应用负责在启动期间(最常见的是在 main 函数中)初始化 TraceDriver 并在全局注册 Tracer。

如需注册跟踪器,请调用 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()
    })
}

基本用法

TraceSink 定义了跟踪数据包的序列化方式。Tracing 2.0 附带一个使用 Perfetto 跟踪数据包格式的 Sink 实现。TraceDriver 提供 Tracer 的句柄,可用于完成跟踪。

Tracer 初始化(在 Android 上自动初始化或在 JVM 上手动初始化)后,使用全局 Tracer.global 实例发出跟踪事件。

如果您选择在某些应用变体中完全不进行跟踪,还可以使用 TraceDriver 停用应用中的所有跟踪点。您可以选择在创建 TraceDriver 实例时为 isCategoryEnabled 提供实现,从而为给定 category 启用跟踪点。

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

以下是在 JVM 上使用 Tracer.global 发出跟踪事件的基本示例,包括手动设置:

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

这会生成以下跟踪记录。

基本 Perfetto 跟踪记录的屏幕截图

图 1. 基本 Perfetto 跟踪记录的屏幕截图。

您可以看到,系统填充了正确的进程和线程轨迹,并且它们生成了一个运行了 100 毫秒的轨迹部分 basic。

跟踪记录部分(或切片)可以嵌套在同一轨道上,以表示重叠的事件。这里给出了一个示例,

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

这会生成以下跟踪记录。

包含嵌套部分的 Perfetto 基本跟踪记录的屏幕截图

图 2. 包含嵌套部分的 Perfetto 基本轨迹的屏幕截图。

您可以看到主线程轨道中存在重叠事件。很明显,processImage 会在同一线程上调用 loadImage 和 sharpen。

在跟踪记录部分中添加其他元数据

有时,将额外的上下文元数据附加到跟踪切片会很有用,这样可以获取更多详细信息。此类元数据的一些示例可能包括用户所在的 nav destination,或最终可能决定函数执行时长的 input arguments。

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

这会产生以下结果。请注意,Arguments 部分包含生成 slice 时添加的键值对。

包含额外元数据的基本 Perfetto 轨迹的屏幕截图

图 3. 包含其他元数据的基本 Perfetto 跟踪记录的屏幕截图。

上下文传播

使用 Kotlin 协程或其他有助于处理并发工作负载的类似框架时,Tracing 2.0 支持上下文传播的概念。通过示例能够对此获得最深刻的理解。

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

这会产生以下结果。

Perfetto 跟踪记录的屏幕截图,其中包含上下文传播

图 4。 包含上下文传播的基本 Perfetto 跟踪记录的屏幕截图。

上下文传播功能可让您更轻松地直观呈现执行流程。您可以确切地看到哪些任务是相关的(与其他任务相关联),以及 Threads 暂停和恢复的确切时间。

例如,您可以看到切片 main 衍生了 taskOne 和 taskTwo。 之后,两个线程都处于非活跃状态,因为协程由于使用 delay 而被挂起。

手动传播

有时,当您将使用 Kotlin 协程的并发工作负载与 Java Executor 实例混合使用时,将上下文从一个传播到另一个可能会很有用。示例如下:

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

这会产生以下结果。

手动传播上下文的 Perfetto 跟踪记录的屏幕截图

图 5. 手动传播上下文的基本 Perfetto 跟踪记录的屏幕截图。

您可以看到,执行在 CoroutineContext 中启动,随后切换到 Java Executor,但我们仍然能够使用上下文传播。

与系统跟踪记录结合使用

androidx.tracing 库不会捕获 CPU 调度、内存用量以及应用与操作系统的一般交互等信息。这是因为该库提供了一种执行低开销进程内跟踪的方法。

不过,将系统跟踪记录与进程内跟踪记录合并,并在需要时将其可视化为单个跟踪记录,是非常简单的事情。这是因为 Perfetto UI 支持在统一的时间轴上直观呈现来自设备的多个跟踪文件。

为此,您可以按照此处的说明,使用 Perfetto UI 启动系统跟踪会话。

您还可以在系统跟踪功能处于开启状态时,使用 Tracing 2.0 API 记录进程内跟踪事件。获得两个跟踪文件后,您可以使用 Perfetto 中的 Open Multiple Trace Files 选项。

在 Perfetto 界面中打开多个跟踪文件

图 6. 在 Perfetto 界面中打开多个跟踪文件。

高级工作流

本部分介绍了您可以使用进程内跟踪库实现的高级工作流。

关联切片

有时,将跟踪记录中的切片归因于更高级别的用户操作或系统事件会很有用。例如,如需将与某些后台工作对应的所有切片归因于通知,您可以执行以下操作:

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

这会产生以下结果。

包含相关切片的 Perfetto 跟踪记录的屏幕截图

图 7. 包含相关切片的 Perfetto 跟踪记录的屏幕截图。

添加调用堆栈信息

主机端工具(例如编译器插件和注解处理器)也可以选择将调用堆栈信息嵌入到跟踪记录中,以便轻松找到负责在跟踪记录中生成跟踪记录部分的文件、类或方法。

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

这会产生以下结果。

包含调用堆栈信息的 Perfetto 轨迹的屏幕截图

图 8. 包含调用堆栈信息的 Perfetto 跟踪记录的屏幕截图。