Makrobenchmark yazın

Uygulamanızın daha büyük kullanım alanlarını test etmek için Macrobenchmark kitaplığını kullanın. Uygulama başlatma ve karmaşık kullanıcı arayüzü işlemleri (ör. LazyColumn kaydırma veya animasyon çalıştırma) bu kapsamdadır. Kodunuzun daha küçük alanlarını test etmek istiyorsanız Microbenchmark başlıklı makaleyi inceleyin. Bu sayfada, Macrobenchmark kitaplığının nasıl ayarlanacağı gösterilmektedir.

Kitaplık, karşılaştırma sonuçlarını Android Studio konsoluna ve daha fazla ayrıntı içeren bir JSON dosyasına aktarır. Ayrıca, Android Studio'da yükleyip analiz edebileceğiniz izleme dosyaları da sağlar.

Sürekli Entegrasyonda Karşılaştırma bölümünde açıklandığı gibi, Macrobenchmark kitaplığını sürekli entegrasyon (CI) ortamında kullanın.

Temel Profiller oluşturmak için Macrobenchmark'ı kullanabilirsiniz. Öncelikle Macrobenchmark kitaplığını kurun, ardından temel profil oluşturabilirsiniz.

Macrobenchmark, Jetpack Compose ile oluşturulan kullanıcı arayüzlerini test etmek için önerilen araçtır. Oluşturma düğümlerinizle etkileşim kuran UI Automator testlerini nasıl yazacağınızı öğrenmek için Birlikte çalışabilirlik bölümüne bakın.

Proje ayarlama

Macrobenchmark'ı Android Studio'nun en yeni sürümüyle kullanmanızı öneririz.

Macrobenchmark modülünü ayarlama

Makro karşılaştırmalar, uygulamanızı ölçen testleri çalıştırmaktan sorumlu olan ve uygulama kodunuzdan ayrı bir com.android.test modülü gerektirir.

Android Studio'da, Macrobenchmark modülü kurulumunu basitleştiren bir şablon bulunur. Karşılaştırma modülü şablonu, projenizde uygulama modülü tarafından oluşturulan uygulamayı ölçmek için otomatik olarak bir modül oluşturur. Bu modül, örnek bir başlangıç karşılaştırması içerir.

Modül şablonunu kullanarak yeni bir modül oluşturmak için aşağıdakileri yapın:

1. Android Studio'daki Proje panelinde projenizi veya modülünüzü sağ tıklayıp Yeni > Modül'ü seçin.

2. Şablonlar bölmesinden Karşılaştırma'yı seçin. Yeni Macrobenchmark modülü için paket ve modül adının yanı sıra hedef uygulamayı (yani karşılaştırması yapılacak uygulamayı) özelleştirebilirsiniz.

3. Son'u tıklayın.

Şekil 1. Karşılaştırma modülü şablonu.

Uygulamayı kurma

Macrobenchmark'ın hedefi olarak bilinen bir uygulamayı karşılaştırmak için uygulamanın profileable olması gerekir. Bu sayede, performansı etkilemeden ayrıntılı izleme bilgileri okunabilir. Modül sihirbazı, <profileable> etiketini uygulamanın AndroidManifest.xml dosyasına otomatik olarak ekler.

Hedef uygulamanın, Macrobenchmark kitaplığının profil yakalama, sıfırlama ve gölgelendirici önbelleği temizleme işlemlerini etkinleştirmek için ihtiyaç duyduğu ProfilerInstaller 1.3 veya sonraki bir sürümü içerdiğinden emin olun.

Karşılaştırmalı değerlendirme yapılan uygulamayı, yayınlanan sürüme veya üretime mümkün olduğunca yakın olacak şekilde yapılandırın. Uygulamayı hata ayıklanamaz olarak ve tercihen sadeleştirme etkin şekilde ayarlayın. Bu, performansı artırır. Bunu genellikle, aynı şekilde çalışan ancak hata ayıklama anahtarlarıyla yerel olarak imzalanan sürüm varyantının bir kopyasını oluşturarak yaparsınız. Alternatif olarak, Gradle'ın bunu sizin için yapmasını sağlamak üzere initWith kullanabilirsiniz:

Kotlin

buildTypes {
    getByName("release") {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
    }

    create("benchmark") {
        initWith(getByName("release"))
        signingConfig = signingConfigs.getByName("debug")
    }
}

Modern

buildTypes {
    release {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "keep-rules.pro"
        )
        // In real app, this would use its own release keystore
        signingConfig = signingConfigs.getByName("debug")
        baselineProfile.automaticGenerationDuringBuild = true
    }
}
build.gradle.kts

Karşılaştırmayı çalıştırmanın, Şekil 2'de gösterildiği gibi uygulamanızın doğru varyantını hem derlediğinden hem de test ettiğinden emin olmak için aşağıdakileri yapın:

1. Gradle senkronizasyonu gerçekleştirin.
2. Derleme Değişkenleri panelini açın.
3. Hem uygulamanın hem de Macrobenchmark modülünün karşılaştırma varyantını seçin.

Şekil 2. Karşılaştırma varyantını seçin.

Not: Projenizi Macrobenchmark'a hazır olacak şekilde nasıl ayarlayacağınızla ilgili referans için örnek Macrobenchmark modülüne bakın.

(İsteğe bağlı) Çok modüllü uygulama oluşturma

Uygulamanızda birden fazla Gradle modülü varsa derleme komut dosyalarınızın hangi derleme değişkenini derleyeceğini bildiğinden emin olun. matchingFallbacks özelliğini :macrobenchmark ve :app modüllerinizin benchmark derleme türüne ekleyin. Gradle modüllerinizin geri kalanı öncekiyle aynı yapılandırmaya sahip olabilir.

Kotlin

create("benchmark") {
    initWith(getByName("release"))
    signingConfig = signingConfigs.getByName("debug")

    matchingFallbacks += listOf("release")
 }

Modern

benchmark {
    initWith buildTypes.release
    signingConfig signingConfigs.debug

    matchingFallbacks = ['release']
 }

Bu işlem yapılmazsa yeni eklenen benchmark derleme türü, derlemenin başarısız olmasına neden olur ve aşağıdaki hata mesajını verir:

> Could not resolve project :shared.
     Required by:
         project :app
      > No matching variant of project :shared was found.
      ...

Projenizdeki derleme değişkenlerini seçerken :app ve :macrobenchmark modülleri için benchmark, uygulamanızdaki diğer modüller için ise release seçeneğini belirleyin (Şekil 3'te gösterildiği gibi):

Şekil 3. Yayın ve karşılaştırma derleme türleri seçili olan çok modüllü proje için karşılaştırma varyantları.

Daha fazla bilgi için Varyant eşleştirme ile ilgili derleme hatalarını çözme başlıklı makaleyi inceleyin.

(İsteğe bağlı) Ürün türlerini ayarlama

Uygulamanızda birden fazla ürün türü ayarlanmışsa :macrobenchmark modülünü, uygulamanızın hangi ürün türünü oluşturup karşılaştıracağını bilecek şekilde yapılandırın.

Bu sayfadaki örneklerde, aşağıdaki snippet'te gösterildiği gibi :app modülündeki iki ürün türü (demo ve production) kullanılmıştır:

Kotlin

flavorDimensions += "environment"
productFlavors {
    create("demo") {
        dimension = "environment"
        // ...
    }
    create("production") {
        dimension = "environment"
        // ...
    }
}

Modern

flavorDimensions 'environment'
productFlavors {
    demo {
        dimension 'environment'
        // ...
    }

    production {
        dimension 'environment'
        // ...
    }
}

Bu yapılandırma olmadan, birden fazla Gradle modülünün neden olduğu hataya benzer bir derleme hatası alabilirsiniz:

Could not determine the dependencies of task ':macrobenchmark:connectedBenchmarkAndroidTest'.
> Could not determine the dependencies of null.
   > Could not resolve all task dependencies for configuration ':macrobenchmark:benchmarkTestedApks'.
      > Could not resolve project :app.
        Required by:
            project :macrobenchmark
         > The consumer was configured to find a runtime of a component, as well as attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'benchmark', attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '7.3.0'. However we cannot choose between the following variants of project :app:
             -   demoBenchmarkRuntimeElements
             -   productionBenchmarkRuntimeElements
           All of them match the consumer attributes:
           ...

Aşağıdaki iki bölümde, karşılaştırmayı birden fazla ürün türüyle yapılandırma yöntemleri açıklanmaktadır.

missingDimensionStrategy kullanma

:macrobenchmark modülünün defaultConfig bölümünde missingDimensionStrategy belirtildiğinde derleme sistemi, tür boyutuna geri döner. Modülde bulamazsanız hangi boyutların kullanılacağını belirtin. Aşağıdaki örnekte, varsayılan boyut olarak production varyantı kullanılmıştır:

Kotlin

defaultConfig {
    missingDimensionStrategy("environment", "production")
}

Modern

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

Bu sayede :macrobenchmark modülü, yalnızca belirtilen ürün türünü derleyip karşılaştırabilir. Bu, yalnızca bir ürün türünün karşılaştırma için uygun yapılandırmaya sahip olduğunu bildiğiniz durumlarda faydalıdır.

:macrobenchmark modülünde ürün türlerini tanımlama

Başka ürün türleri oluşturmak ve karşılaştırmak istiyorsanız bunları :macrobenchmark modülünde tanımlayın. :app modülündeki gibi belirtin ancak productFlavors değerini yalnızca bir dimension değerine atayın. Başka bir ayar yapılması gerekmez:

Kotlin

flavorDimensions += "environment"
productFlavors {
    create("demo") {
        dimension = "environment"
    }
    create("production") {
        dimension = "environment"
    }
}

Modern

flavorDimensions 'environment'
productFlavors {
    demo {
        dimension 'environment'
    }

    production {
        dimension 'environment'
    }
}

Projeyi tanımlayıp senkronize ettikten sonra Derleme Değişkenleri bölmesinden ilgili derleme değişkenini seçin (Şekil 4'te gösterildiği gibi):

Şekil 4. "productionBenchmark" ve "release" seçili olan ürün türlerini gösteren projenin karşılaştırma varyantları.

Daha fazla bilgi için Varyant eşleştirme ile ilgili derleme hatalarını çözme başlıklı makaleyi inceleyin.

Macrobenchmark sınıfı oluşturma

Karşılaştırma testi, Macrobenchmark kitaplığındaki MacrobenchmarkRule JUnit4 kural API'si aracılığıyla sağlanır. Hedef uygulamanın nasıl çalıştırılacağı ve karşılaştırılacağıyla ilgili çeşitli koşulları belirtmenize olanak tanıyan bir measureRepeated yöntemi içerir.

En azından hedef uygulamanın packageName, ölçmek istediğiniz metrics ve karşılaştırmanın kaç iterations çalıştırılması gerektiğini belirtmeniz gerekir.

Kotlin

@LargeTest
@RunWith(AndroidJUnit4::class)
class SampleStartupBenchmark {
    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun startup() = benchmarkRule.measureRepeated(
        packageName = TARGET_PACKAGE,
        metrics = listOf(StartupTimingMetric()),
        iterations = DEFAULT_ITERATIONS,
    ) {
        // starts default launch activity
        uiAutomator { startApp(TARGET_PACKAGE) }
    }
}
SampleStartupBenchmark.kt

Karşılaştırmanızı özelleştirmeyle ilgili tüm seçenekler için Karşılaştırmaları özelleştirme bölümüne bakın.

Not: measureBlock uygulamanızın kullanıcı arayüzü öğeleriyle etkileşim kurması gerekiyorsa (ör. FrameTimingMetric ölçümü için bir listeyi kaydırma) UI Automator'ı kullanın. testTagAsResourceId'ı etkinleştirerek Compose değiştiricileriyle etkileşim kurabilirsiniz.

Compose kullanıcı arayüzü etkileşimlerini karşılaştırma

Önceki örnekte uygulama başlatma ölçülürken genellikle kaydırma sırasında kare düşüşleri (takılma) gibi kullanıcı arayüzü performansını ölçmek istersiniz.

Bir Jetpack Compose uygulamasını karşılaştırmak için (ör. LazyColumn kaydırılırken FrameTimingMetric ölçmek için) aşağıdaki snippet'te gösterildiği gibi doğrudan Compose düğümlerinizle etkileşim kurmak üzere UI Automator'ı kullanabilirsiniz.

İpucu: UI Automator'ın Compose öğelerinizi bulmasına izin vermek için üst düzey Compose öğenizin semantik değiştiricisinde testTagAsResourceId = true özelliğini etkinleştirin.

@LargeTest
@RunWith(AndroidJUnit4::class)
class ComposeScrollBenchmark {
    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun scrollLazyColumn() = benchmarkRule.measureRepeated(
        packageName = "com.example.compose.app",
        metrics = listOf(FrameTimingMetric()),
        iterations = 5,
        startupMode = StartupMode.WARM,
        setupBlock = { pressHome() }
    ) {
        startActivityAndWait()

        // Find the Compose node using the testTag defined in your app
        val lazyColumn = device.findObject(By.res("my_lazy_column"))

        // Simulate a scroll gesture to measure FrameTimingMetric
        lazyColumn.setGestureMargin(device.displayWidth / 5)
        lazyColumn.fling(Direction.DOWN)
    }
}

Karşılaştırmayı çalıştırma

Not: Karşılaştırma yaparken durumu korumak için Android 14 (API düzeyi 34) veya sonraki sürümleri kullanın. Macrobenchmark kitaplığı, her derleme için derleme durumunu tamamen sıfırlar. Bu işlem, Android 14'ten önceki Android sürümlerinde APK'nın yeniden yüklenmesini gerektirir. Geçici bir çözüm olarak, uygulama derlemesini ayrı olarak kontrol edin ve CompilationMode.Ignore kullanarak derlemeyi atlayın.

Uygulamanızın cihazınızdaki performansını ölçmek için testi Android Studio'dan çalıştırın. Karşılaştırmaları, Şekil 5'te gösterildiği gibi test sınıfınızın veya yönteminizin yanındaki gutter işlemini kullanarak diğer @Test testlerini çalıştırdığınız şekilde çalıştırabilirsiniz.

Şekil 5. Test sınıfının yanındaki gutter işlemini kullanarak Macrobenchmark'ı çalıştırın.

Ayrıca, connectedCheck komutunu çalıştırarak bir Gradle modülündeki tüm karşılaştırmaları komut satırından çalıştırabilirsiniz:

./gradlew :macrobenchmark:connectedCheck

Aşağıdaki kodu çalıştırarak tek bir test çalıştırabilirsiniz:

./gradlew :macrobenchmark:connectedCheck -P android.testInstrumentationRunnerArguments.class=com.example.macrobenchmark.startup.SampleStartupBenchmark#startup

Not: Son kullanıcı deneyimini temsil eden performans değerleri üretmedikleri için karşılaştırmaları emülatörde çalıştırmanızı önermiyoruz.

Sürekli entegrasyonda karşılaştırmaların nasıl çalıştırılacağı ve izleneceği hakkında bilgi için Sürekli Entegrasyonda Karşılaştırma bölümüne bakın.

Karşılaştırma sonuçları

Başarılı bir karşılaştırma çalıştırmasından sonra metrikler doğrudan Android Studio'da gösterilir ve CI kullanımı için bir JSON dosyasında çıktı olarak verilir. Ölçülen her iterasyon, ayrı bir sistem izi yakalar. Şekil 6'da gösterildiği gibi Test Sonuçları panelindeki bağlantıları tıklayarak bu izleme sonuçlarını açabilirsiniz:

Şekil 6. Macrobenchmark başlatma sonuçları.

İzleme yüklendiğinde Android Studio, analiz edilecek işlemi seçmenizi ister. Seçim, Şekil 7'de gösterildiği gibi hedef uygulama işlemiyle önceden doldurulur:

Şekil 7. Studio izleme işlemi seçimi.

İzleme dosyası yüklendikten sonra Studio, sonuçları CPU Profiler aracında gösterir:

Şekil 8. Studio izi.

JSON raporları ve profil oluşturma izleri de cihazdan ana makineye otomatik olarak kopyalanır. Bunlar, ana makinede aşağıdaki konuma yazılır:

project_root/module/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/device_id/

İzleme dosyalarına manuel olarak erişme

İzleme dosyasını analiz etmek için Perfetto aracını kullanmak istiyorsanız ek adımlar uygulamanız gerekir. Perfetto, izleme sırasında cihazda gerçekleşen tüm işlemleri incelemenize olanak tanır. Android Studio'nun CPU Profiler'ı ise incelemeyi tek bir işlemle sınırlandırır.

Testleri Android Studio'dan veya Gradle komut satırından çağırırsanız izleme dosyaları cihazdan ana makineye otomatik olarak kopyalanır. Bu günlükler, ana makinede aşağıdaki konuma yazılır:

project_root/module/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/device_id/TrivialStartupBenchmark_startup[mode=COLD]_iter002.perfetto-trace

İzleme dosyası ana sisteminizde olduğunda, menüden Dosya > Aç'ı seçerek dosyayı Android Studio'da açabilirsiniz. Bu, önceki bölümde gösterilen profil oluşturma aracı görünümünü gösterir.

Yapılandırma hataları

Uygulama yanlış yapılandırılmışsa (hata ayıklanabilir veya profili oluşturulamaz) Macrobenchmark, yanlış veya eksik bir ölçüm bildirmek yerine hata döndürür. androidx.benchmark.suppressErrors bağımsız değişkeniyle bu hataları gizleyebilirsiniz.

Macrobenchmark, bir emülatörü veya düşük pilli bir cihazı ölçmeye çalışırken de hata döndürür. Bu durum, çekirdek kullanılabilirliğini ve saat hızını tehlikeye atabilir.

Karşılaştırmaları özelleştirme

measureRepeated işlevi, kitaplığın hangi metrikleri toplayacağını, uygulamanızın nasıl başlatılıp derleneceğini veya karşılaştırmanın kaç iterasyon çalıştıracağını etkileyen çeşitli parametreleri kabul eder.

Metrikleri yakalama

Metrikler, karşılaştırmalarınızdan elde edilen temel bilgi türüdür. Aşağıdaki metrikler kullanılabilir:

• StartupTimingMetric
• FrameTimingMetric
• TraceSectionMetric

Metrikler hakkında daha fazla bilgi için Makro karşılaştırma metriklerini yakalama başlıklı makaleyi inceleyin.

Özel etkinliklerle izleme verilerini iyileştirme

Uygulamanızı, izleme raporunun geri kalanıyla birlikte görülen ve uygulamanıza özgü sorunları belirlemenize yardımcı olabilecek özel izleme etkinlikleriyle donatmak faydalı olabilir. Özel izleme etkinlikleri oluşturma hakkında daha fazla bilgi edinmek için Özel etkinlikleri tanımlama başlıklı makaleyi inceleyin.

CompilationMode

Makro karşılaştırmalar, uygulamanın ne kadarının DEX bayt kodundan (APK içindeki bayt kodu biçimi) makine diline (önceden derlenmiş C++'a benzer) önceden derlenmesi gerektiğini tanımlayan bir CompilationMode belirtebilir.

Makro karşılaştırmalar varsayılan olarak CompilationMode.DEFAULT ile çalıştırılır. Bu, Android 7 (API düzeyi 24) ve sonraki sürümlere varsa bir Temel Profil yükler. Android 6 (API düzeyi 23) veya daha eski bir sürüm kullanıyorsanız derleme modu, varsayılan sistem davranışı olarak APK'yı tamamen derler.

Hedef uygulama hem Temel Profil hem de ProfileInstaller kitaplığını içeriyorsa Temel Profil yükleyebilirsiniz.

Android 7 ve sonraki sürümlerde, farklı düzeylerde önceden (AOT) derleme veya JIT önbelleğe alma işlemlerini taklit etmek için cihaz üzerinde ön derleme miktarını etkileyecek şekilde CompilationMode değerini özelleştirebilirsiniz. CompilationMode.Full, CompilationMode.Partial, CompilationMode.None ve CompilationMode.Ignore sayfalarına göz atın.

Bu özellik, ART derleme komutları üzerine kurulmuştur. Her karşılaştırma, karşılaştırmalar arasında karışıklık olmaması için başlamadan önce profil verilerini temizler.

StartupMode

Etkinlik başlatma işlemi gerçekleştirmek için önceden tanımlanmış bir başlatma modu iletebilirsiniz: COLD, WARM veya HOT. Bu parametre, etkinliğin nasıl başlatılacağını ve testin başındaki işlem durumunu değiştirir.

Uyarı: StartupMode.COLD kullanılırsa uygulama işlemi, setupBlock ve measureBlock yürütülürken sonlandırılır. Böylece işlem başlatılmadan uygulama hazırlığı yapılabilir. İşlemin etkin kalması gerekiyorsa işlemi yeniden başlatmadan etkinlikleri yeniden başlatan StartupMode.WARM yöntemini kullanın veya startupMode değerini null olarak ayarlayıp setupBlock içinde killProcess yöntemini çağırın.

Başlatma türleri hakkında daha fazla bilgi edinmek için Uygulama başlatma süresi başlıklı makaleyi inceleyin.

Örnekler

GitHub'daki deponun Macrobenchmark Örneği bölümünde örnek bir proje bulabilirsiniz.

Geri bildirim gönderme

Jetpack Macrobenchmark ile ilgili sorunları bildirmek veya özellik istekleri göndermek için herkese açık Issue Tracker'a bakın.