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 ingin menguji area yang lebih kecil pada kode Anda, lihat library Microbenchmark.

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 Menjalankan benchmark dalam Continuous Integration.

Profil Baseline dapat dibuat menggunakan Macrobenchmark. Ikuti panduan di bawah ini untuk menyiapkan library Marcobenchmark kemudian membuat Profil Baseline.

Penyiapan project

Sebaiknya gunakan Macrobenchmark dengan Android Studio versi terbaru, karena ada fitur baru dalam versi IDE tersebut yang terintegrasi dengan Macrobenchmark.

Menyiapkan modul Macrobenchmark

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

Di Android Studio Bumblebee, 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 klik New > Module.

  2. Pilih Benchmark dari panel Templates.

  3. Anda dapat menyesuaikan aplikasi target (aplikasi yang akan diukur), serta nama paket dan modul untuk modul macrobenchmark baru.

  4. Klik Finish.

Template Modul Benchmark

Menyiapkan aplikasi

Untuk mengukur aplikasi (disebut target macro benchmark), aplikasi tersebut harus profileable, yang memungkinkan pembacaan informasi rekaman aktivitas mendetail tanpa memengaruhi performa. Wizard modul menambahkan tag <profileable> secara otomatis ke file AndroidManifest.xml aplikasi.

Konfigurasi aplikasi benchmark seidentik mungkin dengan versi rilis (atau produksi). Siapkan aplikasi 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:

Groovy

buildTypes {
    release {
        minifyEnabled true
        shrinkResources true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }

    benchmark {
        initWith buildTypes.release
        signingConfig signingConfigs.debug
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'benchmark-rules.pro'
    }
}

Kotlin

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

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

Lakukan sinkronisasi Gradle, buka panel Build Variants di sebelah kiri, lalu pilih varian benchmark aplikasi dan modul Macrobenchmark. Hal ini memastikan bahwa menjalankan benchmark akan mem-build dan menguji varian yang benar dari aplikasi Anda:

Pilih varian benchmark

(Opsional) Menyiapkan aplikasi multi-modul

Jika aplikasi Anda memiliki lebih dari satu modul Gradle, Anda harus memastikan skrip build mengetahui varian build yang akan dikompilasi. Tanpanya, buildType 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.
      ...

Anda dapat memperbaiki masalah ini dengan menambahkan properti matchingFallbacks ke buildType benchmark dari modul :macrobenchmark dan :app Anda. Modul Gradle lainnya dapat memiliki konfigurasi yang sama seperti sebelumnya.

Groovy

benchmark {
    initWith buildTypes.release
    signingConfig signingConfigs.debug

    matchingFallbacks = ['release']
}

Kotlin

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

    matchingFallbacks += listOf('release')
}

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

Varian benchmark untuk project multi-modul dengan buildType rilis dan benchmark dipilih

Untuk informasi selengkapnya, lihat pengelolaan dependensi berdasarkan varian.

(Opsional) Menyiapkan ragam produk

Jika memiliki beberapa ragam produk yang ditetapkan di aplikasi, Anda harus mengonfigurasi modul :macrobenchmark, agar mengetahui ragam produk yang akan dibuat dan diukur oleh ragam aplikasi Anda. 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:
           ...

Untuk panduan ini, kita menggunakan dua ragam produk di modul :app -- demo dan production seperti yang dapat Anda lihat di cuplikan berikut:

Groovy

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

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

Kotlin

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

Ada dua cara untuk mengonfigurasi benchmark dengan beberapa ragam produk:

Gunakan missingDimensionStrategy

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

Groovy

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

Kotlin

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 ingin mem-build dan mengukur ragam produk lainnya, Anda harus menentukannya dalam modul :macrobenchmark. Tetapkan dengan cara yang sama seperti di modul :app, tetapi hanya tetapkan productFlavors ke dimension -- yang lain tidak perlu disetel:

Groovy

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

    production {
        dimension 'environment'
    }
}

Kotlin

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

Setelah menentukan dan menyinkronkan project, pilih varian build yang diinginkan dari panel Build Variants:

Varian benchmark untuk project dengan ragam produk yang menampilkan productionBenchmark dan rilis 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 menentukan minimal packageName aplikasi target, metrics apa yang ingin Anda ukur, dan berapa banyak iterations yang harus dijalankan oleh 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 = 5,
        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;
            }
        );
    }
}

Untuk semua opsi tentang cara menyesuaikan benchmark, lihat bagian Menyesuaikan benchmark.

Menjalankan benchmark

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 yang ditunjukkan pada gambar berikut.

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

Atau, untuk menjalankan pengujian tunggal:

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

Lihat bagian Benchmark dalam CI untuk mendapatkan 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 rekaman aktivitas hasil ini dengan mengklik salah satu link di panel Test Results, seperti yang ditunjukkan pada gambar berikut.

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:

Pemilihan proses rekaman aktivitas Studio

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

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:

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

Mengakses file rekaman aktivitas secara manual

Jika Anda ingin menggunakan alat Perfetto untuk menganalisis file rekaman aktivitas, Anda perlu melakukan langkah-langkah tambahan. 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 menjalankan pengujian dari Android Studio atau menggunakan command line Gradle, file rekaman aktivitas akan otomatis disalin dari perangkat ke host. Laporan tersebut ditulis pada mesin host di:

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

Setelah memiliki file rekaman aktivitas di sistem host, Anda dapat membukanya di Android Studio dengan 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.

Error juga ditampilkan saat mencoba mengukur emulator, atau pada perangkat dengan daya baterai lemah, karena hal ini 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 akan dijalankan oleh benchmark.

Merekam metrik

Metrik adalah jenis informasi utama yang diekstrak dari benchmark Anda. Opsi yang tersedia adalah StartupTimingMetric, FrameTimingMetric, dan TraceSectionMetric. Untuk melihat informasi selengkapnya tentang metrik tersebut, lihat halaman Merekam metrik.

Mengoptimalkan data rekaman aktivitas dengan peristiwa kustom

Ada baiknya Anda menginstrumentasikan 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

Macro benchmark 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, macro benchmark dijalankan dengan CompilationMode.DEFAULT, yang menginstal Profil Baseline (jika tersedia) di Android 7 (API level 24) dan yang lebih tinggi. Jika Anda menggunakan Android 6 (API level 23) atau yang lebih rendah, mode kompilasi akan sepenuhnya mengompilasi APK sebagai perilaku sistem default.

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

Di Android 7 dan yang lebih tinggi, 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, dan CompilationMode.None.

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

StartupMode

Untuk memulai aktivitas, Anda dapat meneruskan mode startup yang telah ditentukan (salah satu dari COLD, WARM, atau HOT). Parameter ini mengubah cara aktivitas diluncurkan dan status proses di awal pengujian.

Untuk mempelajari lebih lanjut jenis startup, lihat dokumentasi startup Android Vitals.

Contoh

Contoh project tersedia sebagai bagian dari repositori android/performance-samples di GitHub.

Memberikan masukan

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