Menulis Macrobenchmark

Gunakan library Macrobenchmark untuk menguji kasus penggunaan aplikasi Anda yang lebih besar, termasuk proses memulai aplikasi dan manipulasi UI yang kompleks, seperti men-scroll RecyclerView atau menjalankan animasi. Jika Anda ingin menguji area yang lebih kecil pada kode Anda, lihat library Microbenchmark. Halaman ini menunjukkan cara menyiapkan library Macrobenchmark.

Library ini menampilkan hasil benchmark ke konsol Android Studio dan file JSON dengan detail yang lebih lengkap. Library ini juga menyediakan file rekaman aktivitas yang dapat Anda muat dan analisis di Android Studio.

Gunakan library Macrobenchmark dalam lingkungan continuous integration (CI), seperti yang dijelaskan di Benchmark dalam Continuous Integration.

Anda dapat menggunakan Macrobenchmark untuk membuat Profil Dasar Pengukuran. Pertama-tama, siapkan library Macrobenchmark, lalu Anda dapat membuat Profil Dasar Pengukuran.

Penyiapan project

Sebaiknya Anda menggunakan Macrobenchmark dengan Android Studio versi terbaru karena terdapat fitur IDE yang terintegrasi dengan Macrobenchmark.

Menyiapkan modul Macrobenchmark

Macrobenchmark memerlukan modul com.android.test, yang terpisah dari kode aplikasi, dan bertanggung jawab untuk menjalankan pengujian yang mengukur aplikasi Anda.

Di Android Studio, tersedia template untuk menyederhanakan penyiapan modul Macrobenchmark. Template modul benchmark otomatis membuat modul dalam project Anda untuk mengukur aplikasi yang dibuat oleh modul aplikasi, termasuk contoh benchmark startup.

Untuk menggunakan template modul guna membuat modul baru, lakukan hal berikut:

1. Klik kanan project atau modul di panel Project di Android Studio, lalu pilih New > Module.

2. Pilih Benchmark dari panel Templates. Anda dapat menyesuaikan aplikasi target—yaitu aplikasi yang akan diukur—serta nama paket dan modul untuk modul Macrobenchmark baru.

3. Klik Finish.

Gambar 1. Template modul Benchmark.

Menyiapkan aplikasi

Untuk mengukur aplikasi, atau yang dikenal sebagai target Macrobenchmark, aplikasi harus bersifat profileable. Hal ini memungkinkan pembacaan informasi rekaman aktivitas yang mendetail tanpa memengaruhi performa aplikasi. Wizard modul menambahkan tag <profileable> secara otomatis ke file AndroidManifest.xml aplikasi.

Pastikan aplikasi target menyertakan ProfilerInstaller 1.3 atau yang lebih tinggi, library Macrobenchmark harus memungkinkan pengambilan profil dan reset dan menghapus cache shader.

Konfigurasi aplikasi benchmark seidentik mungkin dengan versi rilis atau produksi. Siapkan sebagai tidak dapat di-debug dan sebaiknya dengan minifikasi aktif, yang akan meningkatkan performa. Anda biasanya melakukan hal ini dengan membuat salinan varian rilis, yang memiliki performa yang sama, tetapi ditandatangani secara lokal dengan kunci debug. Atau, Anda dapat menggunakan initWith untuk memerintahkan Gradle agar melakukannya untuk Anda:

Kotlin

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

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

Groovy

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

Untuk membantu memastikan bahwa menjalankan benchmark akan membangun dan menguji varian aplikasi yang benar, seperti yang ditunjukkan dalam gambar 2, lakukan hal berikut:

1. Lakukan sinkronisasi Gradle.
2. Buka panel Build Variants.
3. Pilih varian benchmark dari aplikasi maupun modul Macrobenchmark.

Gambar 2. Pilih varian benchmark.

Catatan: Lihat contoh modul Macrobenchmark untuk referensi tentang cara menyiapkan project agar siap dengan Macrobenchmark.

(Opsional) Menyiapkan aplikasi multi-modul

Jika aplikasi Anda memiliki lebih dari satu modul Gradle, pastikan skrip build Anda mengetahui varian build mana yang akan dikompilasi. Tambahkan properti matchingFallbacks ke jenis build benchmark dari modul :macrobenchmark dan :app Anda. Modul Gradle lainnya dapat memiliki konfigurasi yang sama seperti sebelumnya.

Kotlin

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

    matchingFallbacks += listOf("release")
 }

Groovy

benchmark {
    initWith buildTypes.release
    signingConfig signingConfigs.debug

    matchingFallbacks = ['release']
 }

Tanpanya, jenis build benchmark yang baru ditambahkan akan menyebabkan build gagal dan memberikan pesan error berikut:

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

Saat memilih varian build dalam project, pilih benchmark untuk modul :app dan :macrobenchmark, serta release untuk modul lain yang Anda miliki di aplikasi, seperti ditunjukkan dalam gambar 3:

Gambar 3. Varian benchmark untuk project multi-modul dengan jenis build rilis dan benchmark dipilih.

Untuk informasi selengkapnya, lihat Menggunakan pengelolaan dependensi berdasarkan varian.

(Opsional) Menyiapkan ragam produk

Jika memiliki beberapa ragam produk yang ditetapkan di aplikasi, Anda harus mengonfigurasi modul :macrobenchmark, agar modul ini mengetahui ragam produk mana dari aplikasi Anda yang akan dibangun dan diukur.

Contoh di halaman ini menggunakan dua ragam produk di modul :app: demo dan production, seperti ditunjukkan dalam cuplikan berikut:

Kotlin

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

Groovy

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

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

Tanpa konfigurasi ini, Anda mungkin mendapatkan error build yang mirip dengan beberapa modul Gradle:

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:
           ...

Dua bagian berikut adalah cara untuk mengonfigurasi benchmark dengan beberapa ragam produk.

Menggunakan missingDimensionStrategy

Menentukan missingDimensionStrategy dalam defaultConfig modul :macrobenchmark akan memberi tahu sistem build untuk kembali ke dimensi ragam produk. Tentukan dimensi yang akan digunakan jika Anda tidak menemukannya dalam modul. Pada contoh berikut, ragam production digunakan sebagai dimensi default:

Kotlin

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

Groovy

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

Dengan cara ini, modul :macrobenchmark hanya dapat mem-build dan menjalankan benchmark ragam produk yang ditentukan, yang berguna jika Anda mengetahui bahwa hanya satu ragam produk yang memiliki konfigurasi yang sesuai untuk diukur.

Menentukan ragam produk di modul :macrobenchmark

Jika Anda ingin membangun dan mengukur ragam produk lainnya, tentukan dalam modul :macrobenchmark. Tetapkan dengan cara yang sama seperti di modul :app, tetapi hanya tetapkan productFlavors ke dimension. Tidak ada setelan lain yang diperlukan:

Kotlin

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

Groovy

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

    production {
        dimension 'environment'
    }
}

Setelah menentukan dan menyinkronkan project, pilih varian build yang relevan dari panel Build Variants, seperti ditunjukkan dalam gambar 4:

Gambar 4. Varian benchmark untuk project dengan ragam produk yang menampilkan "productionBenchmark" dan "release" dipilih.

Untuk informasi selengkapnya, lihat Mengatasi error build yang berkaitan dengan pencocokan varian.

Membuat class macrobenchmark

Pengujian benchmark disediakan melalui API aturan JUnit4 MacrobenchmarkRule di library Macrobenchmark. Class ini berisi metode measureRepeated yang memungkinkan Anda menentukan berbagai kondisi tentang cara menjalankan dan mengukur aplikasi target.

Anda perlu setidaknya menentukan packageName aplikasi target, metrics apa yang ingin Anda ukur dan berapa banyak iterations yang harus dijalankan benchmark.

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

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;
            }
        );
    }
}

Untuk semua opsi terkait menyesuaikan benchmark, lihat bagian Menyesuaikan benchmark.

Menjalankan benchmark

Catatan: Gunakan Android 14 (level API 34) atau yang lebih tinggi untuk mempertahankan status saat menjalankan benchmark. Library Macrobenchmark mereset status kompilasi sepenuhnya untuk setiap kompilasi, yang pada versi Android lebih rendah dari 14 memerlukan penginstalan ulang APK. Sebagai solusi, kontrol kompilasi aplikasi secara terpisah dan lewati kompilasi menggunakan CompilationMode.Ignore.

Jalankan pengujian dari dalam Android Studio untuk mengukur performa aplikasi di perangkat Anda. Anda dapat menjalankan benchmark dengan cara yang sama seperti menjalankan @Test lainnya menggunakan tindakan gutter di samping class atau metode pengujian, seperti ditunjukkan dalam gambar 5.

Gambar 5. Menjalankan Macrobenchmark dengan tindakan gutter di samping class pengujian.

Anda juga dapat menjalankan semua benchmark dalam modul Gradle dari command line dengan menjalankan perintah connectedCheck:

./gradlew :macrobenchmark:connectedCheck

Anda dapat menjalankan satu pengujian dengan menjalankan perintah berikut:

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

Catatan: Sebaiknya jangan menjalankan benchmark pada emulator karena tidak menghasilkan angka performa yang mewakili pengalaman pengguna akhir.

Lihat Benchmark dalam Continuous Integration untuk mengetahui informasi tentang cara menjalankan dan memantau benchmark dalam continuous integration.

Hasil benchmark

Setelah benchmark selesai berjalan, metrik akan ditampilkan langsung di Android Studio dan juga merupakan output untuk penggunaan CI dalam file JSON. Setiap iterasi pengukuran merekam aktivitas sistem yang terpisah. Anda dapat membuka hasil rekaman aktivitas ini dengan mengklik link di panel Test Results, seperti ditunjukkan dalam gambar 6:

Gambar 6. Hasil startup Macrobenchmark.

Setelah rekaman aktivitas dimuat, Android Studio akan meminta Anda untuk memilih proses yang akan dianalisis. Pemilihan sudah diisi sebelumnya dengan proses aplikasi target, seperti ditunjukkan dalam gambar 7:

Gambar 7. Pemilihan proses rekaman aktivitas Studio.

Setelah file rekaman aktivitas dimuat, Studio akan menampilkan hasilnya di CPU profiler alat ini:

Gambar 8. Rekaman aktivitas Studio.

Laporan JSON dan setiap rekaman aktivitas pembuatan profil juga otomatis disalin dari perangkat ke host. Laporan tersebut ditulis pada mesin host di lokasi berikut:

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

Mengakses file rekaman aktivitas secara manual

Jika Anda ingin menggunakan Perfetto untuk menganalisis file pelacakan, ada langkah-langkah ekstra yang diperlukan. Perfetto memungkinkan Anda memeriksa semua proses yang terjadi di seluruh perangkat selama perekaman aktivitas, sementara CPU profiler Android Studio membatasi pemeriksaan pada satu proses.

Jika Anda memanggil pengujian dari Android Studio atau dari command line Gradle, file rekaman aktivitas akan otomatis disalin dari perangkat ke host. File tersebut ditulis pada mesin host di lokasi berikut:

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

Jika memiliki file rekaman aktivitas di sistem host, Anda dapat membukanya di Android Studio lewat File > Open di menu. Tindakan ini akan menunjukkan tampilan alat profiler yang ditampilkan di bagian sebelumnya.

Error konfigurasi

Jika aplikasi salah dikonfigurasi—dapat di-debug atau tidak dapat dibuat profil—Macrobenchmark akan menampilkan error, bukan melaporkan pengukuran yang salah atau tidak lengkap. Anda dapat menyembunyikan error ini dengan argumen androidx.benchmark.suppressErrors.

Macrobenchmark juga menampilkan error saat mencoba mengukur emulator atau pada perangkat dengan daya baterai lemah, yang dapat membahayakan ketersediaan inti dan kecepatan clock.

Menyesuaikan benchmark

Fungsi measureRepeated menerima berbagai parameter yang memengaruhi metrik yang dikumpulkan library, cara aplikasi dimulai dan dikompilasi, atau jumlah iterasi yang dijalankan benchmark.

Merekam metrik

Metrik adalah jenis informasi utama yang diekstrak dari benchmark Anda. Metrik berikut tersedia:

• StartupTimingMetric
• FrameTimingMetric
• TraceSectionMetric

Untuk mengetahui informasi selengkapnya tentang metrik, lihat Mengambil metrik Macrobenchmark.

Meningkatkan data rekaman aktivitas dengan peristiwa kustom

Sebaiknya Anda menginstrumentasi aplikasi dengan peristiwa rekaman aktivitas kustom, yang ditampilkan bersama laporan rekaman aktivitas lainnya dan dapat membantu menunjukkan masalah khusus untuk aplikasi Anda. Untuk mempelajari lebih lanjut cara membuat peristiwa rekaman aktivitas kustom, lihat panduan Menentukan peristiwa kustom.

CompilationMode

Macrobenchmark dapat menentukan CompilationMode, yang menetapkan jumlah aplikasi yang harus dikompilasi sebelumnya dari bytecode DEX (format bytecode dalam APK) ke kode mesin (mirip dengan C++ yang telah dikompilasi sebelumnya).

Secara default, Macrobenchmark dijalankan dengan CompilationMode.DEFAULT, yang menginstal Profil Dasar Pengukuran—jika tersedia—di Android 7 (level API 24) dan yang lebih baru. Jika Anda menggunakan Android 6 (level API 23) atau yang lebih lama, mode kompilasi akan sepenuhnya mengompilasi APK sebagai perilaku sistem default.

Anda dapat menginstal Profil Dasar Pengukuran jika aplikasi target berisi Profil Dasar Pengukuran dan library ProfileInstaller.

Di Android 7 dan yang lebih baru, Anda dapat menyesuaikan CompilationMode untuk memengaruhi jumlah prakompilasi di perangkat guna meniru berbagai level kompilasi ahead of time (AOT) atau cache JIT. Lihat CompilationMode.Full, CompilationMode.Partial, CompilationMode.None, dan CompilationMode.Ignore.

Fitur ini dibuat berdasarkan perintah kompilasi ART. Setiap benchmark akan menghapus data profil sebelum dimulai, untuk memastikan tidak ada gangguan di antara benchmark.

StartupMode

Untuk memulai aktivitas, Anda dapat meneruskan mode startup yang telah ditentukan: COLD, WARM, atau HOT. Parameter ini mengubah cara aktivitas diluncurkan dan status proses pada awal pengujian.

Peringatan: Jika StartupMode.COLD digunakan, proses aplikasi akan dihentikan antara eksekusi setupBlock dan measureBlock untuk memungkinkan persiapan aplikasi tanpa memulai prosesnya. Jika Anda perlu agar proses tetap aktif, gunakan StartupMode.WARM, yang memulai ulang aktivitas tanpa memulai ulang proses, atau tetapkan startupMode ke null dan panggil killProcess() dalam setupBlock.

Untuk mempelajari lebih lanjut jenis startup, lihat Waktu startup aplikasi.

Contoh

Project contoh tersedia di Contoh Macrobenchmark repositori di GitHub.

Memberikan masukan

Untuk melaporkan masalah atau mengirimkan permintaan fitur untuk Jetpack Macrobenchmark, lihat issue tracker publik.