從 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,並使用TraceSink將 Perfetto 追蹤檔寫入Context.noBackupFilesDir/perfetto_traces/。在全域註冊產生的
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 沒有自動啟動機制。應用程式負責在啟動期間初始化 TraceDriver,並在全域註冊 Tracer,最常見的做法是在 main 函式中執行。
如要註冊追蹤器,請呼叫 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 隨附 Sink 實作,使用 Perfetto 追蹤封包格式。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)
}
}
}
這會產生下列追蹤記錄。
圖 1. 基本 Perfetto 追蹤記錄的螢幕截圖。
您會看到系統填入正確的程序和執行緒追蹤記錄,並產生單一追蹤記錄區段 basic,執行時間為 100 毫秒。
追蹤記錄區段 (或切片) 可在同一軌跡上建立巢狀結構,代表重疊的事件。我們來看個例子
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") {
// ...
}
}
這會產生下列追蹤記錄。
圖 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 時新增的鍵/值組合。
圖 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")
}
}
這會產生以下結果。
圖 4. 基本 Perfetto 追蹤記錄的螢幕截圖,其中包含背景資訊傳播。
Context Propagation 可大幅簡化執行流程的視覺化。您可以清楚看到哪些工作相關 (與其他工作連結),以及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()
}
}
這會產生以下結果。
圖 5. 基本 Perfetto 追蹤記錄的螢幕截圖,其中包含手動傳播的內容。
您可以看到執行作業在 CoroutineContext 中啟動,隨後切換至 Java Executor,但我們仍可使用內容傳播。
與系統追蹤記錄結合
androidx.tracing 程式庫不會擷取 CPU 排程、記憶體用量,以及應用程式與作業系統的一般互動等資訊。這是因為程式庫提供執行低負擔程序內追蹤的方法。
不過,您可以輕鬆合併系統追蹤記錄和程序內追蹤記錄,並視需要以單一追蹤記錄的形式呈現。這是因為 Perfetto UI 支援在統一時間軸上,以視覺化方式呈現裝置的多個追蹤檔。
如要執行這項操作,請按照這裡的操作說明,使用 Perfetto UI 啟動系統追蹤工作階段。
您也可以在系統追蹤功能開啟時,使用 Tracing 2.0 API 記錄程序內追蹤事件。取得兩份追蹤檔後,您可以使用 Perfetto 的 Open Multiple Trace Files 選項。
圖 6. 在 Perfetto UI 中開啟多個追蹤檔。
進階工作流程
本節說明可透過程序內追蹤程式庫實作的進階工作流程。
關聯切片
有時,將追蹤記錄中的切片歸因於更高級別的使用者動作或系統事件,會很有幫助。舉例來說,如要將對應至某些背景工作的所有配量歸因於通知的一部分,可以執行以下操作:
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)
}
}
這會產生以下結果。
圖 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)
}
}
}
這會產生以下結果。
圖 8. Perfetto 追蹤記錄的螢幕截圖,其中包含呼叫堆疊資訊。