Makrobenchmark yazın

Uygulama başlatma ve RecyclerView kaydırma veya animasyon çalıştırma gibi karmaşık kullanıcı arayüzü değişiklikleri dahil olmak üzere uygulamanızın daha geniş kullanım alanlarını test etmek için Makrobenchmark kitaplığını kullanın. Kodunuzun daha küçük alanlarını test etmek istiyorsanız Microbenchmark kitaplığı'na bakın. Bu sayfada Makrobenchmark kitaplığının nasıl ayarlanacağı gösterilmektedir.

Kitaplık, karşılaştırma sonuçlarını hem Android Studio konsoluna hem de daha ayrıntılı bilgiler içeren bir JSON dosyasına çıkarı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, Makrobenchmark kitaplığını sürekli entegrasyon (CI) ortamında kullanın.

Temel Profiller oluşturmak için Makrobenchmark'ı kullanabilirsiniz. Öncelikle Makrobenchmark kitaplığını ayarlayın, ardından Referans Profili oluşturabilirsiniz.

Proje kurulumu

Makrobenchmark ile entegre olan IDE özellikleri için Makrobenchmark'ı Android Studio'nun en son sürümüyle kullanmanızı öneririz.

Makrobenchmark modülünü ayarlama

Makrobenchmark'lar, uygulamanızı ölçen testleri çalıştırmaktan sorumlu olan ve uygulama kodunuzdan ayrı bir com.android.test modülü gerektirir.

Android Studio'da, Makrobenchmark modülü kurulumunu basitleştirmek için bir şablon bulunmaktadır. Karşılaştırma modülü şablonu, projenizde bir uygulama modülü tarafından derlenen uygulamayı ölçmek için otomatik olarak bir modül oluşturur. Bu modül, örnek bir başlangıç karşılaştırması da 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ın ve Yeni > Modül'ü seçin.

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

  3. Son'u tıklayın.

Karşılaştırma Modülü şablonu

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

Uygulamayı kurma

Makrobenchmark'ın hedefi olarak bilinen bir uygulamayı karşılaştırmak için uygulamanın, performansı etkilemeden ayrıntılı iz bilgilerinin okunmasını sağlayan profileable olması gerekir. Modül sihirbazı, <profileable> etiketini otomatik olarak uygulamanın AndroidManifest.xml dosyasına ekler.

Hedef uygulamanın ProfilerInstaller 1.3 veya sonraki bir sürümü içerdiğinden emin olun. Bu sürüm, Makrobenchmark kitaplığının profil yakalamayı etkinleştirme, sıfırlama ve gölgelendirici önbellek temizlemeyi etkinleştirmesi için gereklidir.

Karşılaştırmalı uygulamayı sürüm sürümüne veya üretime mümkün olduğunca yakın yapılandırın. Hata ayıklaması mümkün olmayan ve tercihen küçültme özelliği açık olacak şekilde ayarladığınızda performansı artırın. Bunu genellikle sürüm varyantının, aynı performansı gösteren ancak hata ayıklama anahtarlarıyla yerel olarak imzalanan bir kopyasını oluşturarak yaparsınız. Alternatif olarak, initWith kullanarak Gradle'a bu işlemi sizin yerinize gerçekleştirmesini isteyebilirsiniz:

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 {
    getByName("release") {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "proguard-rules.pro"
        )
        // In real app, this would use its own release keystore
        signingConfig = signingConfigs.getByName("debug")
    }
}

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

  1. Gradle senkronizasyonu gerçekleştirin.
  2. Varyant Oluşturma panelini açın.
  3. Hem uygulamanın hem de Makrobenchmark modülünün karşılaştırma varyantını seçin.

Karşılaştırma varyantı seçin

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

(İsteğe bağlı) Çok modüllü uygulama kurun

Uygulamanızda birden fazla Gradle modülü varsa derleme komut dosyalarınızın hangi derleme varyantının derleneceğini bildiğinden emin olun. :macrobenchmark ve :app modüllerinizin benchmark derleme türüne matchingFallbacks özelliği ekleyin. Gradle modüllerinin 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 olmadığında, 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.
      ...

Projenizde derleme varyantlarını seçerken :app ve :macrobenchmark modülleri için benchmark seçeneğini ve uygulamanızda bulunan diğer tüm modüller için Şekil 3'te gösterildiği gibi release seçeneğini belirleyin:

Çok modüllü proje için sürüm ve karşılaştırma derleme türlerinin seçildiği karşılaştırma varyantları

3. Şekil. Sürüm ve karşılaştırma derleme türlerinin seçili olduğu çok modüllü proje için karşılaştırma varyantları.

Daha fazla bilgi için Varyanta duyarlı bağımlılık yönetimini kullanma başlıklı makaleyi inceleyin.

(İsteğe bağlı) Ürün çeşitlerini ayarlama

Uygulamanızda ayarlanmış birden fazla ürün aroması varsa :macrobenchmark modülünü yapılandırarak uygulamanızın hangi ürün arosunu geliştireceğini ve karşılaştıracağını bilebilir.

Bu sayfadaki örneklerde, aşağıdaki snippet'te gösterildiği gibi :app modülündeki iki ürün çeşidi kullanılmaktadır: demo ve production:

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 çok Gradle modülüne 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üm, karşılaştırmayı birden fazla ürün çeşidiyle yapılandırmanın yollarıdır.

missingDimensionStrategy öğesini kullanma

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

Kotlin

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

Modern

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

Bu şekilde, :macrobenchmark modülü yalnızca belirtilen ürün aromasını oluşturabilir ve karşılaştırabilir. Bu da yalnızca tek bir ürün çeşidinin, karşılaştırılacak uygun yapılandırmaya sahip olduğunu biliyorsanız faydalıdır.

:macrobenchmark modülünde ürün aromaları tanımlayın

Başka ürün aromaları oluşturmak ve bunları karşılaştırmak istiyorsanız :macrobenchmark modülünde bunları tanımlayın. :app modülündekine benzer bir şekilde belirtin ancak productFlavors öğesini bir dimension öğesine yalnızca atayın. Başka ayar 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, Şekil 4'te gösterildiği gibi Varyant Derleme bölmesinden ilgili derleme varyantını seçin:

Ürün çeşitlerinin productionBenchmark ve yayının seçili olduğu karşılaştırma varyantları

4. Şekil. Proje için "productionBenchmark" ve "release" seçeneklerinin seçilmiş ürün çeşitlerini içeren karşılaştırma varyantları.

Daha fazla bilgi için Varyant eşleştirmeyle ilgili derleme hatalarını çözme bölümüne bakın.

Bir makro karşılaştırma sınıfı oluşturma

Karşılaştırma testi, Makrobenchmark kitaplığındaki MacrobenchmarkRule JUnit4 kural API'si aracılığıyla sağlanır. Hedef uygulamayı çalıştırma ve karşılaştırma ile ilgili çeşitli koşulları belirtmenizi sağlayan bir measureRepeated yöntemi içerir.

En azından hedef uygulamanın packageName değerini, hangi metrics metriği ölçmek istediğinizi ve karşılaştırmanın kaç iterations çalışması 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,
        setupBlock = {
            // Press home button before each run to ensure the starting activity isn't visible.
            pressHome()
        }
    ) {
        // starts default launch activity
        startActivityAndWait()
    }
}

Java

@LargeTest
@RunWith(AndroidJUnit4.class)
public class SampleStartupBenchmark {
    @Rule
    public MacrobenchmarkRule benchmarkRule = new MacrobenchmarkRule();

    @Test
    public void startup() {
        benchmarkRule.measureRepeated(
            /* packageName */ TARGET_PACKAGE,
            /* metrics */ Arrays.asList(new StartupTimingMetric()),
            /* iterations */ 5,
            /* measureBlock */ scope -> {
                // starts default launch activity
                scope.startActivityAndWait();
                return Unit.INSTANCE;
            }
        );
    }
}

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.

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

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 oluk işlemini kullanarak diğer herhangi bir @Test ile aynı şekilde çalıştırabilirsiniz.

Test sınıfının yanında oluk hareketli makro karşılaştırma
yapın

5. Şekil. Makrobenchmark'ı test sınıfının yanında oluk işlemli olarak çalıştırın.

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

./gradlew :macrobenchmark:connectedCheck

Aşağıdakini yürüterek tek bir test çalıştırabilirsiniz:

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

Sürekli entegrasyonda karşılaştırmaları çalıştırma ve izleme hakkında bilgi için Sürekli Entegrasyon'da 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örüntülenir ve bir JSON dosyasında CI kullanımı için çıkış yapılır. Ölçülen her iterasyon, ayrı bir sistem izlemeyi kaydeder. Bu iz sonuçlarını, şekilde 6'da gösterildiği gibi Test Sonuçları bölmesindeki bağlantıları tıklayarak açabilirsiniz:

Makrobenchmark başlatma
sonuçları

6. Şekil. Makrobenchmark başlangıç sonuçları.

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

Studio trace işlemi seçimi

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

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

Studio
Trace

8. Şekil. Stüdyo izleme'yi tıklayın.

JSON raporları ve tüm 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

Bir izleme dosyasını analiz etmek için Perfetto aracını kullanmak istiyorsanız uygulamanız gereken ek adımlar vardır. Perfetto, iz sırasında cihazda gerçekleşen tüm işlemleri incelemenize olanak tanırken Android Studio'nun CPU profil oluşturucusu 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ı otomatik olarak cihazdan ana makineye 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/TrivialStartupBenchmark_startup[mode=COLD]_iter002.perfetto-trace

Barındırıcı sisteminizde izleme dosyası olduğunda bu dosyayı Android Studio'daki menüden Dosya > Aç'ı kullanarak açabilirsiniz. Bu işlem, önceki bölümde gösterilen profil aracı görünümünü gösterir.

Yapılandırma hataları

Uygulama yanlış yapılandırılmışsa (hata ayıklanabilir veya profil çıkarılabilir değilse) Makrobenchmark yanlış veya eksik bir ölçümü bildirmek yerine hata döndürür. Bu hataları androidx.benchmark.suppressErrors bağımsız değişkeniyle gizleyebilirsiniz.

Makrobenchmark, bir emülatörü ölçmeye çalışırken veya düşük pilli bir cihazda da hatalar döndürerek temel kullanılabilirlik durumunu ve saat hızını tehlikeye atabilir.

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

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

Metrikleri yakalayın

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

Metrikler hakkında daha fazla bilgi için Makrobenchmark metriklerini yakalama başlıklı makaleye bakın.

Özel etkinliklerle izleme verilerini iyileştirme

Uygulamanıza özel izleme etkinlikleri eklemek faydalı olabilir. Bu etkinlikler, iz raporunun geri kalanıyla birlikte görülür ve uygulamanıza özgü sorunları belirlemenize yardımcı olabilir. Özel izleme etkinlikleri oluşturma hakkında daha fazla bilgi edinmek için Özel etkinlikleri tanımlama bölümüne bakın.

DerlemeModu

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

Makrobenchmark'lar varsayılan olarak CompilationMode.DEFAULT ile çalıştırılır. Bu sayede, Android 7 (API düzeyi 24) ve sonraki sürümlerde Temel Profil yüklenir (varsa). Android 6 (API düzeyi 23) veya önceki bir sürümü kullanıyorsanız derleme modu, APK'yı varsayılan sistem davranışı olarak tam olarak derler.

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

Android 7 ve sonraki sürümlerde CompilationMode özelliğini, cihaz üzerinde önceden derleme miktarını etkileyecek şekilde özelleştirerek önceden derleme veya JIT önbelleğe alma işlemlerinin farklı seviyelerini taklit edebilirsiniz. Bkz. CompilationMode.Full, CompilationMode.Partial, CompilationMode.None ve CompilationMode.Ignore.

Bu özellik, ART derleme komutlarına dayanır. Her karşılaştırma, karşılaştırmalar arasında herhangi bir karışma olmamasına yardımcı olmak için profil verilerini başlamadan önce temizler.

BaşlangıçModu

Bir etkinlik başlangıcı gerçekleştirmek için önceden tanımlanmış bir başlangıç modunu geçirebilirsiniz: COLD, WARM veya HOT. Bu parametre, etkinliğin başlatılma şeklini ve testin başlangıcındaki işlem durumunu değiştirir.

Başlatma türleri hakkında daha fazla bilgi edinmek için Uygulama başlatma süresi bölümüne bakın.

Numuneler

GitHub'daki deponun Macrobenchmark Örneği'nde örnek bir proje mevcuttur.

Geri bildirim gönderme

Sorunları bildirmek veya Jetpack Makrobenchmark için özellik istekleri göndermek için herkese açık sorun izleyicisine bakın.