การติดตามในกระบวนการ

ตั้งแต่ Tracing 2.0 เป็นต้นไป ไลบรารี androidx.tracing จะมี Kotlin API ที่มีค่าใช้จ่ายในการดำเนินการต่ำ ซึ่งช่วยให้คุณบันทึกเหตุการณ์การติดตามในกระบวนการได้ เหตุการณ์เหล่านี้สามารถบันทึกส่วนเวลาและบริบทของส่วนเวลาได้ นอกจากนี้ ไลบรารียังรองรับการเผยแพร่บริบทสำหรับโครูทีน Kotlin ด้วย

ไลบรารีใช้รูปแบบแพ็กเก็ตการติดตาม Perfetto เดียวกันกับที่นักพัฒนาแอป Android คุ้นเคย นอกจากนี้ Tracing 2.0 (ต่างจาก 1.0.0-* API) ยังรองรับแนวคิดของแบ็กเอนด์การติดตามที่เสียบปลั๊กได้และซิงก์ ดังนั้นไลบรารีการติดตามอื่นๆ จึงสามารถปรับแต่งรูปแบบการติดตามเอาต์พุตและวิธีการทำงานของการเผยแพร่บริบทในการใช้งานได้

ความสัมพันธ์

หากต้องการเริ่มการติดตาม คุณต้องกำหนดทรัพยากร Dependency ใน build.gradle.kts

โปรเจ็กต์ Kotlin Multiplatform

ไลบรารีที่ต้องการส่งเหตุการณ์การติดตามเท่านั้นควรขึ้นอยู่กับ API androidx.tracing:tracing ที่มีน้ำหนักเบา แอปที่กำหนดค่าแบ็กเอนด์การติดตามควรใช้ 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 หากคุณรวมทรัพยากร Dependency 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 เพื่อปิดใช้จุดติดตามทั้งหมดในแอปพลิเคชันได้ด้วย หากเลือกที่จะไม่ติดตามเลยในตัวแปรแอปพลิเคชันบางรายการ คุณสามารถเลือกเปิดใช้จุดติดตามสำหรับ category ที่กำหนดได้โดยระบุการติดตั้งใช้งานสำหรับ isCategoryEnabled เมื่อสร้างอินสแตนซ์ของ TraceDriver

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

ต่อไปนี้เป็นตัวอย่างพื้นฐานของการส่งเหตุการณ์การติดตามโดยใช้ Tracer.global ใน JVM รวมถึงการตั้งค่าด้วยตนเอง

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 พื้นฐาน

คุณจะเห็นว่ามีการสร้างแทร็กกระบวนการและชุดข้อความที่ถูกต้อง และแทร็กเหล่านี้สร้างส่วนการติดตาม 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") {
        // ...
    }
}

ซึ่งจะสร้างการติดตามต่อไปนี้

ภาพหน้าจอของการติดตาม 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 Trace พื้นฐานที่มีข้อมูลเมตาเพิ่มเติม

การเผยแพร่บริบท

เมื่อใช้โครูทีน 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 Trace ที่มีการเผยแพร่บริบท

รูปที่ 4 ภาพหน้าจอของ Perfetto Trace พื้นฐานที่มีการส่งต่อบริบท

การส่งผ่านบริบทช่วยให้เห็นภาพขั้นตอนการดำเนินการได้ง่ายขึ้นมาก คุณสามารถดูได้ว่างานใดบ้างที่เกี่ยวข้อง (เชื่อมต่อกับงานอื่นๆ) และดูเวลาที่ Threads ถูกระงับและกลับมาทำงานอีกครั้งได้

ตัวอย่างเช่น คุณจะเห็นว่าส่วน main สร้าง taskOne และ taskTwo หลังจากนั้น ทั้ง 2 เทรดก็ไม่มีการใช้งานเนื่องจาก Coroutine ถูกระงับเนื่องจากการใช้ 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 Trace พื้นฐานที่มีการส่งผ่านบริบทด้วยตนเอง

คุณจะเห็นว่าการดำเนินการเริ่มต้นใน CoroutineContext และเปลี่ยนไปใช้ Java Executor ในภายหลัง แต่เรายังคงใช้การเผยแพร่บริบทได้

รวมกับการติดตามของระบบ

ไลบรารี androidx.tracing จะไม่บันทึกข้อมูล เช่น การจัดกำหนดการ CPU, การใช้งานหน่วยความจำ และการโต้ตอบของแอปพลิเคชันกับระบบปฏิบัติการโดยทั่วไป เนื่องจากไลบรารีมีวิธีดำเนินการการติดตามในกระบวนการที่มีค่าใช้จ่ายต่ำ

อย่างไรก็ตาม การผสานรวมการติดตามของระบบกับการติดตามในกระบวนการและการแสดงภาพเป็นการติดตามเดียวเป็นเรื่องที่ทำได้ง่ายมากหากจำเป็น เนื่องจาก Perfetto UI รองรับการแสดงภาพไฟล์การย้ายข้อมูลหลายไฟล์จากอุปกรณ์ในไทม์ไลน์แบบรวม

โดยคุณสามารถเริ่มเซสชัน System Tracing โดยใช้ Perfetto UI โดยทำตามวิธีการที่นี่

นอกจากนี้ คุณยังบันทึกเหตุการณ์การติดตามในกระบวนการได้โดยใช้ Tracing 2.0 API ขณะที่เปิด System Tracing ไว้ เมื่อมีไฟล์การย้ายข้อมูลทั้ง 2 ไฟล์แล้ว คุณจะใช้ตัวเลือก Open Multiple Trace Files ใน Perfetto ได้

การเปิดไฟล์การติดตามหลายไฟล์ใน Perfetto UI

รูปที่ 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)
    }
}

ซึ่งจะให้ผลลัพธ์ต่อไปนี้

ภาพหน้าจอของ Perfetto Trace ที่มีส่วนที่สัมพันธ์กัน

รูปที่ 7 ภาพหน้าจอของ Perfetto Trace ที่มีส่วนที่สัมพันธ์กัน

เพิ่มข้อมูลสแต็กการเรียกใช้

เครื่องมือฝั่งโฮสต์ เช่น ปลั๊กอินคอมไพเลอร์และโปรเซสเซอร์สำหรับคำอธิบายประกอบ ยังสามารถเลือกฝังข้อมูลสแต็กการเรียกใช้ลงในการติดตาม เพื่อให้ค้นหาไฟล์ คลาส หรือเมธอดที่รับผิดชอบในการสร้างส่วนการติดตามในการติดตามได้สะดวก

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 Trace ที่มีข้อมูลสแต็กการเรียกใช้

รูปที่ 8 ภาพหน้าจอของการติดตาม Perfetto พร้อมข้อมูลสแต็กการเรียกใช้