ردیابی درون‌پردازشی

با شروع Tracing 2.0، کتابخانه androidx.tracing یک Kotlin API با سربار کم ارائه می‌دهد که به شما امکان می‌دهد رویدادهای ردیابی درحال پردازش را ضبط کنید. این رویدادها می‌توانند برش‌های زمان و بافت آن‌ها را ضبط کنند. این کتابخانه همچنین از انتشار بافت برای روال‌های هم‌زمان Kotlin پشتیبانی می‌کند.

این کتابخانه از همان قالب بسته ردیابی Perfetto استفاده می‌کند که توسعه‌دهندگان Android با آن آشنا هستند. همچنین، Tracing 2.0 (برخلاف میاناهای برنامه‌سازی کاربردی 1.0.0-*) از مفهوم پشت‌افزارهای ردیابی قابل‌اتصال و سینک‌ها پشتیبانی می‌کند، بنابراین سایر کتابخانه‌های ردیابی می‌توانند قالب ردیابی خروجی و نحوه عملکرد انتشار زمینه را در پیاده‌سازی خود سفارشی‌سازی کنند.

وابستگی‌ها

برای شروع ردیابی، باید وابستگی‌ها را در build.gradle.kts تعریف کنید.

پروژه‌های Kotlin چندپلاتفرمی

کتابخانه‌هایی که فقط باید رویدادهای ردیابی را منتشر کنند باید به میانای برنامه‌سازی کاربردی سبک 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

در 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 پایه

شکل ۱. ضبط صفحه‌نمایش از ردیابی Perfetto پایه.

می‌توانید ببینید که فرایند و قطعه‌های رشته صحیح پر شده‌اند و یک بخش ردیابی 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 پایه با بخش‌های تودرتو

شکل ۲. نماگرفت از ردیابی 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 پایه با فراداده اضافی

شکل ۳. ضبط صفحه‌نمایش از ردیابی 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 با انتشار بافت

شکل ۴. ضبط صفحه‌نمایش از ردیابی 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 با انتشار بافت دستی

شکل ۵. نماگرفت از ردیابی Perfetto پایه با انتشار بافت دستی.

می‌توانید ببینید که اجرا در CoroutineContext شروع شده است و متعاقباً به Java Executor تغییر کرده است، اما همچنان توانستیم از انتشار بافت استفاده کنیم.

ترکیب با ردگیری‌های سیستم

کتابخانه androidx.tracing اطلاعاتی مانند زمان‌بندی واحد پردازش مرکزی، استفاده از حافظه، و تعامل برنامه با سیستم‌عامل را به‌طور کلی ضبط نمی‌کند. دلیل آن این است که این کتابخانه روشی برای انجام ردیابی درون‌فرایندی با سربار کم ارائه می‌دهد.

بااین‌حال، ادغام ردگیری‌های سیستم با ردگیری‌های درون‌فرایند و تجسم آن‌ها به‌عنوان یک ردگیری واحد درصورت نیاز، بسیار ساده است. دلیلش این است که Perfetto UI از تجسم چندین فایل ردیابی از یک دستگاه در یک خط زمان واحد پشتیبانی می‌کند.

برای انجام این کار، می‌توانید با دنبال کردن دستورالعمل‌های اینجا، جلسه ردیابی سیستم را بااستفاده از Perfetto UI شروع کنید.

همچنین می‌توانید رویدادهای ردیابی درحال پردازش را بااستفاده از Tracing 2.0 API ضبط کنید، درحالی‌که ردیابی سیستم روشن است. وقتی هر دو فایل ردیابی را داشتید، می‌توانید از گزینه Open Multiple Trace Files در Perfetto استفاده کنید.

باز کردن چند فایل ردیابی در واسط کاربر Perfetto

شکل ۶. درحال باز کردن چند فایل ردیابی در واسط کاربر 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 با برش‌های مرتبط

شکل ۷. نماگرفت از ردیابی 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 با اطلاعات پشته فراخوانی

شکل ۸. نماگرفت ردیابی Perfetto با اطلاعات پشته فراخوانی.