التتبُّع أثناء المعالجة

بدءًا من الإصدار 2.0 من Tracing، توفّر مكتبة androidx.tracing واجهة برمجة تطبيقات Kotlin منخفضة النفقات تتيح لك تسجيل أحداث التتبُّع أثناء المعالجة. يمكن لهذه الأحداث التقاط شرائح الوقت وسياقها. تتيح المكتبة أيضًا نشر السياق لبرامج Kotlin coroutines.

تستخدم المكتبة تنسيق حزمة تتبُّع Perfetto نفسه الذي يعرفه مطوّرو برامج Android. بالإضافة إلى ذلك، تتيح واجهة Tracing 2.0 (على عكس واجهات برمجة التطبيقات 1.0.0-*) استخدام الخلفيات القابلة للتوصيل لتتبُّع الأخطاء والمستودعات، ما يتيح لمكتبات تتبُّع الأخطاء الأخرى تخصيص تنسيق تتبُّع الأخطاء الناتج، وطريقة عمل نشر السياق في عملية التنفيذ.

الطلبات التابعة

لبدء التتبُّع، عليك تحديد التبعيات في build.gradle.kts.

مشاريع Kotlin Multiplatform

يجب أن تعتمد المكتبات التي تحتاج فقط إلى إرسال أحداث التتبُّع على واجهة برمجة التطبيقات 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، إذا أدرجت تبعية 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

On the JVM, there's no automatic bootstrapping mechanism. يكون التطبيق مسؤولاً عن إعداد 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 على جهاز Java الافتراضي، بما في ذلك الإعداد اليدوي:

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 أساسي مع بيانات وصفية إضافية

نشر السياق

عند استخدام وظائف Kotlin coroutines أو غيرها من إطارات العمل المشابهة التي تساعد في أعباء العمل المتزامنة، تتيح ميزة 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، ثم انتقل إلى Executor في Java، ولكن ظلّ بإمكاننا استخدام ميزة "نشر السياق".

الدمج مع سجلّات تتبُّع النظام

لا تسجّل مكتبة androidx.tracing معلومات مثل جدولة وحدة المعالجة المركزية (CPU) واستخدام الذاكرة وتفاعل التطبيق مع نظام التشغيل بشكل عام. ويرجع ذلك إلى أنّ المكتبة توفّر طريقة لإجراء عمليات تتبُّع منخفضة التكلفة أثناء المعالجة.

ومع ذلك، من السهل جدًا دمج سجلّات تتبّع النظام مع سجلّات التتبّع أثناء المعالجة وعرضها كسجلّ تتبّع واحد إذا لزم الأمر. ويرجع ذلك إلى أنّ Perfetto UI يتيح عرض ملفات تتبُّع متعددة من جهاز على مخطط زمني موحّد.

لإجراء ذلك، يمكنك بدء جلسة تتبُّع النظام باستخدام Perfetto UI من خلال اتّباع التعليمات الواردة هنا.

يمكنك أيضًا تسجيل أحداث التتبُّع أثناء المعالجة باستخدام واجهة برمجة التطبيقات Tracing 2.0، عندما تكون ميزة "تتبُّع النظام" مفعَّلة. بعد الحصول على ملفَي التتبُّع، يمكنك استخدام خيار Open Multiple Trace Files في Perfetto.

فتح ملفات تتبُّع متعددة في واجهة مستخدم 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 مع معلومات حزمة التنفيذ