بدءًا من الإصدار 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)
}
}
}
يؤدي ذلك إلى إنشاء التتبُّع التالي.
الشكل 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 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")
}
}
يؤدي هذا إلى النتيجة التالية.
الشكل 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()
}
}
يؤدي هذا إلى النتيجة التالية.
الشكل 5: لقطة شاشة لتتبُّع Perfetto أساسي مع نشر السياق يدويًا
يمكنك ملاحظة أنّ التنفيذ بدأ في CoroutineContext، ثم انتقل إلى Executor في Java، ولكن ظلّ بإمكاننا استخدام ميزة "نشر السياق".
الدمج مع سجلّات تتبُّع النظام
لا تسجّل مكتبة androidx.tracing معلومات مثل جدولة وحدة المعالجة المركزية (CPU) واستخدام الذاكرة وتفاعل التطبيق مع نظام التشغيل بشكل عام. ويرجع ذلك إلى أنّ المكتبة توفّر طريقة لإجراء عمليات تتبُّع منخفضة التكلفة أثناء المعالجة.
ومع ذلك، من السهل جدًا دمج سجلّات تتبّع النظام مع سجلّات التتبّع أثناء المعالجة
وعرضها كسجلّ تتبّع واحد إذا لزم الأمر. ويرجع ذلك إلى أنّ Perfetto UI
يتيح عرض ملفات تتبُّع متعددة من جهاز على مخطط زمني موحّد.
لإجراء ذلك، يمكنك بدء جلسة تتبُّع النظام باستخدام Perfetto UI من خلال
اتّباع التعليمات الواردة هنا.
يمكنك أيضًا تسجيل أحداث التتبُّع أثناء المعالجة باستخدام واجهة برمجة التطبيقات Tracing 2.0، عندما تكون ميزة "تتبُّع النظام" مفعَّلة. بعد الحصول على ملفَي التتبُّع، يمكنك استخدام خيار 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)
}
}
يؤدي هذا إلى النتيجة التالية.
الشكل 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 مع معلومات حزمة التنفيذ