Makrobenchmark yazın

Uygulama başlatma ve bir RecyclerView'i kaydırma veya animasyonları çalıştırma gibi karmaşık kullanıcı arayüzü manipülasyonları gibi uygulamanızın daha geniş kullanım alanlarını test etmek için Macrobenchmark kitaplığını kullanın. Kodunuzun daha küçük alanlarını test etmek istiyorsanız Mikrobenchmark kitaplığı'na bakın. Bu sayfada Macrobenchmark kitaplığının nasıl oluşturulacağı açıklanmaktadır.

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

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

Temel Profiller oluşturmak için Macrobenchmark'ı kullanabilirsiniz. Önce Macrobenchmark kitaplığını ayarlayın, ardından Temel Profil oluşturabilirsiniz.

Proje kurulumu

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

Macrobenchmark modülünün kurulumu

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

Android Studio'da, Macrobenchmark modülü kurulumunu basitleştirmek için bir şablon mevcuttur. 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ı da sunar.

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ölmesinde Karşılaştırma'yı seçin. Hedef uygulamayı (yani karşılaştırılacak uygulamayı) ve yeni Macrobenchmark modülü için paket ve modül adını özelleştirebilirsiniz.

3. Son'u tıklayın.

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

Uygulamayı kur

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

Hedef uygulamanın ProfilerInstaller 1.3 veya sonraki bir sürümü içerdiğinden emin olun. Macrobenchmark kitaplığının, profil yakalamayı etkinleştirmesi, sıfırlaması ve gölgelendirici önbelleği temizleme işlemini etkinleştirmesi için gerekir.

Karşılaştırmalı uygulamayı, sürüm sürümüne veya üretime olabildiğince yakın bir şekilde yapılandırın. Bu ayarı, hata ayıklanamaz ve tercihen performansı artıran küçültme açık olarak ayarlayın. Bunu genellikle sürüm varyantının bir kopyasını oluşturarak yaparsınız. Bu kopya, aynı işlemi gerçekleştirir ancak hata ayıklama anahtarlarıyla yerel olarak imzalanır. Alternatif olarak, initWith kullanarak Gradle'a bu işlemi sizin yerinize yapmasını da isteyebilirsiniz:

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

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

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")
    }
}
build.gradle.kts

Karşılaştırmayı çalıştırmanın, uygulamanızın doğru varyantını derleyip test etmesini sağlamak için Şekil 2'de gösterildiği gibi aşağıdakileri yapın:

1. Gradle senkronizasyonu gerçekleştirin.
2. Varyant Derleme 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.

(İ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ğini ekleyin. Gradle modüllerinizin geri kalanı öncekiyle aynı yapılandırmaya sahip olabilir.

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

    matchingFallbacks += listOf("release")
 }

benchmark {
    initWith buildTypes.release
    signingConfig signingConfigs.debug

    matchingFallbacks = ['release']
 }

Bu olmadan, 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, uygulamanızda bulunan diğer tüm modüller için Şekil 3'te gösterildiği gibi release değerini seçin:

Şekil 3. Çok modüllü projeler için karşılaştırma varyantları ve sürüm ve karşılaştırma derleme türleri seçildi.

Daha fazla bilgi için Varyanta duyarlı bağımlılık yönetimini kullanma bölümüne bakın.

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

Uygulamanızda ayarlanmış birden fazla ürün aroması varsa :macrobenchmark modülünü, uygulamanızın hangi ürün aromasını geliştirip karşılaştıracağını bilmesi için yapılandırın.

Bu sayfadaki örnekler, aşağıdaki snippet'te gösterildiği gibi :app modülündeki iki ürün aromasını kullanmaktadır: demo ve production:

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

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

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

Bu yapılandırma olmadan, birden fazla 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ümde, karşılaştırmayı birden çok ürün çeşidiyle yapılandırmanın yolları verilmektedir.

Eksik Boyut Stratejisini kullanın

:macrobenchmark modülünün defaultConfig öğesinde missingDimensionStrategy belirtilmesi, derleme sistemine aroma boyutuna yedeklenmesini bildirir. Modülde bulamıyorsanız hangi boyutları kullanacağınızı belirtin. Aşağıdaki örnekte, varsayılan boyut olarak production türü kullanılmıştır:

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

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

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

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

Farklı ürün aromalarını geliştirip karşılaştırmak istiyorsanız bunları :macrobenchmark modülünde tanımlayın. :app modülünde olduğu gibi belirtin ancak bir dimension öğesine yalnızca productFlavors değerini atayın. Başka ayar gerekmez:

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

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:

4.Şekil Projenin "productionBenchmark" ve "sürüm" seçeneklerinin seçili olduğu ürün aromalarını içeren karşılaştırma varyantları.

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

Makrobenchmark 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 çalıştırılması ve karşılaştırılması için çeşitli koşullar belirtmenize olanak tanıyan bir measureRepeated yöntemi içerir.

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

@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()
    }
}
SampleStartupBenchmark.kt

@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ünü inceleyin.

Karşılaştırma yapın

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

5. Şekil. Macrobenchmark'ı test sınıfının yanında çukur işlemle çalıştırın.

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

./gradlew :macrobenchmark:connectedCheck

Aşağıdaki komutu çalıştırarak 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 edinmek 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ının ardından, metrikler doğrudan Android Studio'da görüntülenir ve CI kullanımı için bir JSON dosyasında gösterilir. Ölçülen her iterasyon, ayrı bir sistem izi yakalar. Bu iz sonuçlarını, şekil 6'da gösterildiği gibi Test Sonuçları bölmesindeki bağlantıları tıklayarak açabilirsiniz:

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

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

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

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

8. Şekil. Studio izlemesi.

JSON raporları ve profil oluşturma izleri de cihazdan ana makineye otomatik olarak kopyalanır. Bunlar ana makinede aşağıdaki konumda 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 bazı ek adımlardan yararlanabilirsiniz. Perfetto, izleme sırasında cihaz genelinde gerçekleşen tüm işlemleri incelemenize olanak tanırken Android Studio'nun CPU profil oluşturucusu, 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 konumda 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 makine sisteminizdeyken dosyayı Android Studio'da menüde Dosya > Aç ile açabilirsiniz. Burada, önceki bölümde gösterilen profil aracı görünümü gösterilmektedir.

Yapılandırma hataları

Uygulama yanlış yapılandırılmışsa (hata ayıklanabilir veya profillenemez) Macrobenchmark 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.

Macrobenchmark, bir emülatörü ölçmeye çalışırken veya düşük pilli bir cihazda ölçüm yapmaya çalışırken de hatalar döndürür. Bu da temel kullanılabilirliği ve saat hızını olumsuz etkileyebilir.

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

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

Metrikleri yakalayın

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 Macrobenchmark metriklerini yakalama bölümüne bakın.

Özel etkinliklerle izleme verilerini iyileştirme

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

DerlemeMod

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

Macrobenchmark'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 bir Temel Profil (varsa) yüklenir. Android 6 (API düzeyi 23) veya önceki sürümleri kullanıyorsanız derleme modu, APK'yı varsayılan sistem davranışı olarak tamamen derler.

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

Android 7 ve sonraki sürümlerde CompilationMode öğesini, cihaz üzerinde önceden derleme miktarını etkileyecek şekilde özelleştirerek farklı düzeylerde önceden (AOT) derleme veya JIT önbelleğe alma işlemini taklit edebilirsiniz. Bkz. CompilationMode.Full, CompilationMode.Partial, CompilationMode.None ve CompilationMode.Ignore.

Bu özellik, ART derleme komutlarını temel alır. Her karşılaştırma, karşılaştırmalar arasında müdahale olmamasını sağlamak için profil verilerini başlamadan önce temizler.

BaşlangıçModu

Bir etkinlik başlatma işlemi 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 bölümünde örnek bir proje bulabilirsiniz.

Geri bildirim gönderme

Jetpack Macrobenchmark ile ilgili sorunları bildirmek veya özellik isteği göndermek için herkese açık sorun izleyiciyi kullanabilirsiniz.