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.

Anda juga dapat menggunakan library Macrobenchmark dalam lingkungan continuous integration (CI) seperti yang dijelaskan di Menjalankan benchmark dalam Continuous Integration.

Penyiapan project

Sebaiknya gunakan Macrobenchmark dengan Android Studio versi terbaru (Bumblebee 2021.1.1 atau yang lebih baru), 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.

Bumblebee (atau yang lebih baru)

Di Android Studio Bumblebee 2021.1.1, 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

Arctic Fox

Di Arctic Fox, Anda akan membuat modul library, dan mengonversinya menjadi modul pengujian.

  1. Klik kanan project atau modul di panel Project di Android Studio, lalu klik New > Module.
  2. Pilih Android Library di panel Templates.
  3. Ketik macrobenchmark untuk nama modul.
  4. Setel Minimum SDK ke API 23: Android M
  5. Klik Finish.

Mengonfigurasi modul library baru

Mengubah file Gradle

Sesuaikan build.gradle modul Macrobenchmark sebagai berikut:

  1. Ubah plugin dari com.android.library menjadi com.android.test. 
    apply plugin 'com.android.test'
  2. Tambahkan properti modul pengujian tambahan yang diperlukan dalam blok android {}:

    Groovy

    android {
    // ...
    // Note that your module name may have different name
    targetProjectPath = ":app"
    // Enable the benchmark to run separately from the app process
    experimentalProperties["android.experimental.self-instrumenting"] = true

    buildTypes {
        // declare a build type to match the target app's build type
        benchmark {
            debuggable = true
            signingConfig = debug.signingConfig
        }
    }
}
    build.gradle

    Kotlin

    android {
    // ...
    // Note that your module name may have different name
    targetProjectPath = ":app"
    // Enable the benchmark to run separately from the app process
    experimentalProperties["android.experimental.self-instrumenting"] = true

    buildTypes {
        // declare a build type to match the target app's build type
        create("benchmark") {
            isDebuggable = true
            signingConfig = signingConfigs.getByName("debug")
        }
    }
}

  3. Ubah semua dependensi dengan nama testImplementation atau androidTestImplementation menjadi implementation.

  4. Tambahkan dependensi pada library Macrobenchmark: 
    implementation 'androidx.benchmark:benchmark-macro-junit4:1.1.0-beta03'

  5. Hanya izinkan buildType benchmark untuk modul ini. Setelah blok android{}, tetapi sebelum blok dependencies{}, tambahkan:

    Groovy

    androidComponents {
    beforeVariants(selector().all()) {
        // enable only the benchmark buildType, since we only want to measure close to release performance
        enabled = buildType == 'benchmark'
    }
}
    build.gradle

    Kotlin

    androidComponents {
    beforeVariants {
        // enable only the benchmark buildType, since we only want to measure close to release performance
        it.enable = it.buildType == "benchmark"
    }
}

  6. Sederhanakan struktur direktori.

    Dalam modul com.android.test, hanya ada satu direktori sumber, untuk semua pengujian. Hapus direktori sumber lain, termasuk src/test dan src/androidTest, karena keduanya tidak digunakan.

Menyiapkan aplikasi

Untuk mengukur aplikasi (disebut target macro benchmark), aplikasi tersebut harus profileable, yang memungkinkan pembacaan informasi rekaman aktivitas mendetail. Aktifkan dalam tag <application> AndroidManifest.xml aplikasi:

<!-- enable profiling by macrobenchmark -->
<profileable
    android:shell="true"
    tools:targetApi="q" />
AndroidManifest.xml

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
build.gradle

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

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.

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 terkait cara aplikasi target dijalankan dan diukur.

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

Mengakses file rekaman aktivitas secara manual

Jika Anda menggunakan Android Studio versi lama (sebelum Arctic Fox 2020.3.1), atau 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.