Tracing 2.0'dan itibaren androidx.tracing kitaplığı, işlem içi izleme etkinliklerini yakalamanıza olanak tanıyan düşük ek yük içeren bir Kotlin API'si sağlar. Bu etkinlikler, zaman dilimlerini ve bağlamlarını yakalayabilir. Kitaplık, Kotlin eş yordamları için bağlam yayılımını da destekler.
Kitaplık, Android geliştiricilerinin aşina olduğu Perfetto izleme paketi biçimini kullanır. Ayrıca Tracing 2.0 (1.0.0-* API'lerinin aksine) takılabilir izleme arka uçları ve havuzlar kavramını destekler. Böylece diğer izleme kitaplıkları, çıkış izleme biçimini ve bağlam yayılımının kendi uygulamalarında nasıl çalıştığını özelleştirebilir.
Bağımlılıklar
İzlemeye başlamak için build.gradle.kts dosyanızda bağımlılıkları tanımlamanız gerekir.
Kotlin Multiplatform projeleri
Yalnızca izleme etkinlikleri yayınlaması gereken kitaplıklar, basit androidx.tracing:tracing API'sine bağlı olmalıdır. İzleme arka ucunu yapılandıran uygulamalar da androidx.tracing:tracing-wire'e bağlı olmalıdır.
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")
}
}
}
}
Yalnızca Android projeleri
Yalnızca Android'i hedefliyorsanız uygulamanızın veya kitaplığınızın build.gradle.kts dosyasına aşağıdakileri ekleyin:
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")
}
Başlatma ve keşif
İzleme etkinliklerini kaydedebilmeniz için izleme altyapısını başlatmanız gerekir. Bunun için bir AbstractTraceDriver oluşturmanız ve Tracer değerini global olarak kaydetmeniz gerekir.
Android
Android'de, androidx.tracing:tracing-wire bağımlılığını eklerseniz başlatma işlemi, uygulama başlatılırken androidx.startup kitaplığı kullanılarak otomatik olarak gerçekleşir.
Varsayılan olarak bu otomatik başlatma işlemi şunları yapar:
Perfetto izleme dosyalarını
Context.noBackupFilesDir/perfetto_traces/dizinine yazan birTraceSinkileTraceDriveroluşturur.Elde edilen
Tracerdeğerini global olarak kaydeder.
TraceDriver örneğini özelleştirme
Yapılandırmayı özelleştirmeniz gerekiyorsa (ör. izleme dosyalarının kaydedildiği yeri değiştirmek veya özel bir TraceSink kullanmak için) kendi AbstractTraceDriver örneğinizi sağlayabilirsiniz.
Yapılandırmayı özelleştirmek için Application sınıfınızın AbstractTraceDriver.Factory'i uygulamasını sağlayın:
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)
}
}
Otomatik başlatıcı, Application alt sınıfınızın Factory uyguladığını algılar ve özel sürücü fabrikanızı kullanır.
JVM
JVM'de otomatik önyükleme mekanizması yoktur. Uygulama, başlatma sırasında (genellikle main işlevinizde) TraceDriver öğesini başlatmaktan ve Tracer öğesini genel olarak kaydetmekten sorumludur.
İzleyiciyi kaydetmek için Tracer.setGlobalTracer() işlevini çağırın.
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()
})
}
Temel kullanım
TraceSink, izleme paketlerinin nasıl serileştirileceğini tanımlar. Tracing 2.0, Perfetto izleme paketi biçimini kullanan bir Sink uygulamasıyla birlikte gelir. TraceDriver, Tracer için bir tanıtıcı sağlar ve bir izlemeyi tamamlamak için kullanılabilir.
Tracer, Android'de otomatik olarak veya JVM'de manuel olarak başlatıldıktan sonra izleme etkinlikleri yayınlamak için global Tracer.global örneğini kullanın.
Bazı uygulama varyantlarında hiç izleme yapmamayı tercih ederseniz uygulamadaki tüm izleme noktalarını devre dışı bırakmak için TraceDriver özelliğini de kullanabilirsiniz. TraceDriver örneği oluştururken isCategoryEnabled için bir uygulama sağlayarak belirli bir category için izleme noktalarını etkinleştirebilirsiniz.
val driver = TraceDriver(
sink = sink,
isCategoryEnabled = { category ->
// Only enable trace points in the "com.example" package
category.startsWith("com.example")
}
)
Manuel kurulum da dahil olmak üzere JVM'de Tracer.global kullanarak izleme etkinliği yayınlamanın basit bir örneğini aşağıda bulabilirsiniz:
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)
}
}
}
Bu işlem, aşağıdaki izi oluşturur.
Şekil 1. Temel bir Perfetto izinin ekran görüntüsü.
Doğru işlem ve iş parçacığı izlerinin doldurulduğunu ve 100 ms boyunca çalışan tek bir izleme bölümü basic oluşturduklarını görebilirsiniz.
İz bölümleri (veya dilimleri), çakışan etkinlikleri temsil etmek için aynı izde iç içe yerleştirilebilir. Bir örnek verelim.
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") {
// ...
}
}
Bu işlem, aşağıdaki izi oluşturur.
Şekil 2. İç içe yerleştirilmiş bölümler içeren temel bir Perfetto izinin ekran görüntüsü.
Ana iş parçacığı kanalında çakışan etkinlikler olduğunu görebilirsiniz. processImage, aynı ileti dizisinde loadImage ve sharpen yöntemlerini çağırıyor.
İzleme bölümlerine ek meta veriler ekleme
Bazen daha fazla ayrıntı için izleme dilimine ek bağlamsal meta veriler eklemek yararlı olabilir. Bu tür meta verilere örnek olarak kullanıcının bulunduğu nav destination veya bir işlevin ne kadar süreceğini belirleyebilecek input arguments verilebilir.
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)
}
}
}
Bu işlem aşağıdaki sonucu verir. Arguments bölümünün, slice oluşturulurken eklenen anahtar/değer çiftlerini içerdiğini unutmayın.
Şekil 3. Ek meta veriler içeren temel bir Perfetto izinin ekran görüntüsü.
Bağlam yayma
Tracing 2.0, Kotlin eş yordamları veya eşzamanlı iş yüklerine yardımcı olan diğer benzer çerçeveler kullanılırken bağlam yayma kavramını destekler. Bu durumu en iyi bir örnekle açıklayabiliriz.
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")
}
}
Bu işlem aşağıdaki sonucu verir.
Şekil 4. Bağlam yayma özelliğine sahip temel bir Perfetto izinin ekran görüntüsü.
Bağlam yayma, yürütme akışını görselleştirmeyi çok daha kolay hale getirir. Hangi görevlerin birbiriyle ilişkili (bağlantılı) olduğunu ve Threads tam olarak ne zaman askıya alındığını ve devam ettirildiğini görebilirsiniz.
Örneğin, main diliminin taskOne ve taskTwo oluşturduğunu görebilirsiniz.
Ardından, delay kullanımı nedeniyle eş yordamlar askıya alındığı için her iki iş parçacığı da etkin değildi.
Manuel yayma
Bazen, Java Executor örnekleriyle Kotlin eş yordamlarını kullanan eşzamanlı iş yüklerini karıştırırken bağlamı birinden diğerine yaymak yararlı olabilir. Örnek:
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()
}
}
Bu işlem aşağıdaki sonucu verir.
Şekil 5. Manuel bağlam yayma özelliğine sahip temel bir Perfetto izinin ekran görüntüsü.
Yürütmenin bir CoroutineContext içinde başladığını ve ardından bir Java Executor öğesine geçtiğini görebilirsiniz. Ancak yine de bağlam yayma özelliğini kullanabildik.
Sistem izleriyle birleştirme
androidx.tracing kitaplığı; CPU planlama, bellek kullanımı ve uygulamanın işletim sistemiyle genel etkileşimi gibi bilgileri yakalamaz. Bunun nedeni, kitaplığın düşük ek yük içeren işlem içi izleme yapma imkanı sunmasıdır.
Ancak sistem izlerini işlem içi izlerle birleştirmek ve gerekirse bunları tek bir iz olarak görselleştirmek son derece kolaydır. Bunun nedeni, Perfetto UI aracının bir cihazdaki birden fazla izleme dosyasını birleştirilmiş bir zaman çizelgesinde görselleştirmeyi desteklemesidir.
Bunu yapmak için buradaki talimatları uygulayarak Perfetto UI ile bir sistem izleme oturumu başlatabilirsiniz.
Sistem izleme açıkken Tracing 2.0 API'yi kullanarak işlem içi izleme etkinliklerini de kaydedebilirsiniz. Her iki izleme dosyasına da sahip olduğunuzda Perfetto'da Open Multiple Trace Files seçeneğini kullanabilirsiniz.
Şekil 6. Perfetto kullanıcı arayüzünde birden fazla izleme dosyası açma
Gelişmiş iş akışları
Bu bölümde, işlem içi izleme kitaplığıyla uygulayabileceğiniz gelişmiş iş akışları açıklanmaktadır.
Dilimleri ilişkilendirme
Bazen bir izdeki dilimleri daha üst düzey bir kullanıcı işlemine veya sistem etkinliğine atamak yararlı olabilir. Örneğin, bir bildirimin parçası olarak arka plandaki bazı çalışmalara karşılık gelen tüm dilimleri ilişkilendirmek için şunları yapabilirsiniz:
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)
}
}
Bu işlem aşağıdaki sonucu verir.
Şekil 7. İlişkili dilimler içeren bir Perfetto izinin ekran görüntüsü.
Çağrı yığını bilgileri ekleme
Derleyici eklentileri ve ek açıklama işleyicileri gibi ana makine tarafındaki araçlar da izdeki bir iz bölümünü oluşturmaktan sorumlu dosya, sınıf veya yöntemi bulmayı kolaylaştırmak için çağrı yığını bilgilerini bir ize yerleştirmeyi seçebilir.
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)
}
}
}
Bu işlem aşağıdaki sonucu verir.
Şekil 8. Çağrı yığını bilgilerini içeren Perfetto izinin ekran görüntüsü.