Makrobenchmark yazın

Uygulamanızın daha büyük kullanım alanlarını test etmek için Macrobenchmark kitaplığını kullanın. Bu alanlara uygulama başlatma ve RecyclerView kaydırma veya animasyon çalıştırma gibi karmaşık kullanıcı arayüzü manipülasyonları dahildir. Kodunuzun daha küçük alanlarını test etmek istiyorsanız Microbenchmark kitaplığı'na bakın. Bu sayfada, Macrobenchmark 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ı 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, sürekli entegrasyon (CI) ortamında Macrobenchmark kitaplığını kullanın.

Temel profiller oluşturmak için Macrobenchmark'ı kullanabilirsiniz. Öncelikle Macrobenchmark kitaplığını ayarlayın. Ardından temel profil oluşturabilirsiniz.

Proje ayarlama

IDE'nin Macrobenchmark ile entegre olan özelliklerini kullanmak için Macrobenchmark'ı Android Studio'nun en son 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ünün kurulumunu basitleştirmek için bir şablon bulunur. Karşılaştırma modülü şablonu, örnek bir başlangıç karşılaştırması da dahil olmak üzere bir uygulama modülü tarafından oluşturulan uygulamayı ölçmek için projenizde otomatik olarak bir modül oluşturur.

Yeni bir modül oluşturmak için modül şablonunu kullanmak üzere aşağıdakileri yapın:

1. Android Studio'daki Project (Proje) panelinde projenizi veya modülünüzü sağ tıklayın ve New > Module'ü (Yeni > Modül) seçin.

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

3. Son'u tıklayın.

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

Uygulamayı kurma

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

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

Karşılaştırma yapılan uygulamayı, yayınlanan sürüme veya üretime olabildiğince yakın şekilde yapılandırın. Hata ayıklanamaz olarak ve tercihen küçültme etkin şekilde ayarlayın. Bu, performansı artırır. Bunu genellikle yayın varyantının bir kopyasını oluşturarak yaparsınız. Bu kopya, yayın varyantıyla aynı işlevi görür ancak yerel olarak hata ayıklama anahtarlarıyla imzalanır. Alternatif olarak, Gradle'a bunu sizin için yapmasını söylemek üzere initWith kullanabilirsiniz:

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ırma ölçütünün çalıştırılmasının, uygulamanızın doğru varyantını oluşturup 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. Build Variants (Derleme Varyantları) 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 oluşturma

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. matchingFallbacks özelliğini :macrobenchmark ve :app modüllerinizin benchmark derleme türüne ekleyin. Gradle modüllerinizin geri kalanı, önceki yapılandırmayla aynı 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 modüller için ise release seçeneğini belirleyin (Şekil 3'te gösterildiği gibi):

3.Şekil Yayın ve karşılaştırma derleme türlerinin seçildiği çok modüllü projeler için karşılaştırma varyantları.

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

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

Uygulamanızda birden fazla ürün çeşidi ayarlanmışsa :macrobenchmark modülünü, uygulamanızın hangi ürün çeşidinin oluşturulacağını ve karşılaştırma ölçütü olarak kullanılacağı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 çeşidi (demo ve production) kullanılmaktadır:

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üyle 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 çeşidiyle yapılandırma yöntemleri açıklanmaktadır.

missingDimensionStrategy kullanma

:macrobenchmark modülünün defaultConfig bölümünde missingDimensionStrategy belirtmek, derleme sistemine varyant boyutuna geri dönmesini söyler. Boyutları modülde bulamazsanız hangi boyutların kullanılacağını belirtin. Aşağıdaki örnekte, varsayılan boyut olarak production aroması kullanılmaktadır:

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

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

Bu şekilde, :macrobenchmark modülü yalnızca belirtilen ürün çeşidini oluşturup karşılaştırma yapabilir. Bu, yalnızca bir ürün çeşidinin karşılaştırma için uygun yapılandırmaya sahip olduğunu biliyorsanız yararlıdır.

:macrobenchmark modülünde ürün çeşitlerini tanımlayın

Diğer ürün çeşitlerini oluşturup karşılaştırmak istiyorsanız bunları :macrobenchmark modülünde tanımlayın. :app modülündeki gibi belirtin ancak yalnızca productFlavors öğesini dimension öğesine 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 Build Variants (Derleme Varyantları) bölmesinden ilgili derleme varyantını seçin:

Şekil 4. "productionBenchmark" ve "release" seçili olarak ürün çeşitlerini gösteren proje için karşılaştırma ölçütü varyantları.

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

Makro karşılaştırma testi sınıfı oluşturma

Karşılaştırma testi, Macrobenchmark kitaplığındaki MacrobenchmarkRule JUnit4 kuralı API'si aracılığıyla sağlanır. Bu yöntem, hedef uygulamayı çalıştırma ve karşılaştırma ile 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ışması 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ştirme ile 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. Ş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 tüm @Test'leri çalıştırdığınız şekilde karşılaştırmaları çalıştırabilirsiniz.

5.şekil Test sınıfının yanındaki oluk işlemiyle 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 da çalıştırabilirsiniz:

./gradlew :macrobenchmark:connectedCheck

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

./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 başlıklı makaleyi inceleyin.

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

Başarılı bir karşılaştırma testinden sonra metrikler doğrudan Android Studio'da gösterilir ve CI kullanımına yönelik olarak JSON dosyasına aktarılır. Ölçülen her yineleme ayrı bir sistem izi yakalar. Şekil 6'da gösterildiği gibi, Test Sonuçları bölmesindeki bağlantıları tıklayarak bu izleme sonuçlarını açabilirsiniz:

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

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

Şekil 7. Studio izleme süreci seçimi.

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

Şekil 8. Studio izleme.

JSON raporları ve profil oluşturma izleri de cihazdan ana makineye otomatik olarak kopyalanır. Bunlar, ana makineye 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

Bir izleme 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ırken Android Studio'nun CPU profil aracı incelemeyi tek bir işlemle sınırlar.

Testleri Android Studio'dan veya Gradle komut satırından çağırırsanız izleme dosyaları 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/TrivialStartupBenchmark_startup[mode=COLD]_iter002.perfetto-trace

Ana makine sisteminizde izleme dosyası olduğunda, menüde File > Open (Dosya > Aç) seçeneğini kullanarak dosyayı Android Studio'da açabilirsiniz. Bu, önceki bölümde gösterilen profiler aracı görünümünü gösterir.

Yapılandırma hataları

Uygulama yanlış yapılandırılmışsa (hata ayıklanabilir veya profillendirilemez) Macrobenchmark, yanlış ya da eksik bir ölçüm raporlamak yerine hata döndürür. Bu hataları androidx.benchmark.suppressErrors bağımsız değişkeniyle bastırabilirsiniz.

Macrobenchmark, bir emülatörü veya temel kullanılabilirliği ve saat hızını tehlikeye atabilecek düşük pil seviyesine sahip bir cihazı ölçmeye çalışırken de hatalar döndürür.

Karşılaştırma ölçütlerini ö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ç yineleme çalıştırdığını etkileyen çeşitli parametreleri kabul eder.

Metrikleri yakalama

Metrikler, karşılaştırmalarınızdan çıkarılan 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ünen 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'daki bayt kodu biçimi) makine koduna (önceden derlenmiş C++'ya benzer) önceden derlenmesi gerektiğini tanımlayan bir CompilationMode belirtebilir.

Macrobenchmark'lar varsayılan olarak CompilationMode.DEFAULT ile çalıştırılır. Bu, Android 7 (API düzeyi 24) ve sonraki sürümlerde 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 uygulamada hem Baseline Profile hem de ProfileInstaller kitaplığı varsa Baseline Profile yükleyebilirsiniz.

Android 7 ve sonraki sürümlerde, CompilationMode simgesini özelleştirerek cihaz üzerinde önceden derleme miktarını etkileyebilir ve farklı düzeylerde önceden derleme (AOT) veya JIT önbelleğe alma işlemlerini taklit edebilirsiniz. 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 müdahale olmaması için başlamadan önce profil verilerini temizler.

StartupMode

Bir etkinlik başlatmak için önceden tanımlanmış bir başlangıç modu iletebilirsiniz: COLD, WARM veya HOT. Bu parametre, etkinliğin nasıl başlatılacağını ve testin başlangıcındaki süreç durumunu değiştirir.

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

Örnekler

Örnek proje, GitHub'daki deponun Macrobenchmark Sample bölümünde mevcuttur.

Geri bildirim gönder

Jetpack Macrobenchmark ile ilgili sorunları bildirmek veya özellik istekleri göndermek için Herkese açık sorun izleyiciye bakın.