Kasus penggunaan benchmark dengan Jetpack Macrobenchmark

Macrobenchmark memungkinkan Anda menulis pengujian performa startup dan runtime secara langsung pada aplikasi di perangkat yang menjalankan Android M (API 23) atau yang lebih baru.

Sebaiknya Anda menggunakan Macrobenchmark dengan versi terbaru Android Studio (2020.3.1 Beta 4 atau yang lebih baru), karena ada fitur baru dalam versi IDE tersebut yang terintegrasi dengan Macrobenchmark. Pengguna Android Studio versi sebelumnya dapat menggunakan petunjuk tambahan nanti dalam topik ini untuk menangani file rekaman aktivitas.

Pengujian benchmarking disediakan melalui API aturan JUnit4 MacrobenchmarkRule di library Macrobenchmark:

    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun startup() = benchmarkRule.measureRepeated(
        packageName = "mypackage.myapp",
        metrics = listOf(StartupTimingMetric()),
        iterations = 5,
        startupMode = StartupMode.COLD
    ) { // this = MacrobenchmarkScope
        pressHome()
        val intent = Intent()
        intent.setPackage("mypackage.myapp")
        intent.setAction("mypackage.myapp.myaction")
        startActivityAndWait(intent)
    }
  

    @Rule
    MacrobenchmarkRule benchmarkRule = MacrobenchmarkRule()

    @Test
    void startup() = benchmarkRule.measureRepeated(
        "mypackage.myapp", // packageName
        listOf(StartupTimingMetric()), // metrics
        5, // iterations
        StartupMode.COLD // startupMode
    ) { scope ->
        scope.pressHome()
        Intent intent = Intent()
        intent.setPackage("mypackage.myapp")
        intent.setAction("mypackage.myapp.myaction")
        scope.startActivityAndWait(intent)
    }
  

Metrik ditampilkan langsung di Android Studio dan juga merupakan output untuk Penggunaan CI dalam file JSON.

Penyiapan modul

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

@RunWith(AndroidJUnit4::class)
class SampleStartupBenchmark {
    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun startup() = benchmarkRule.measureRepeated(
        packageName = "mypackage.myapp",
        metrics = listOf(StartupTimingMetric()),
        iterations = 5,
        startupMode = StartupMode.COLD
    ) { // this = MacrobenchmarkScope
        pressHome()
        val intent = Intent()
        intent.setPackage("mypackage.myapp")
        intent.setAction("mypackage.myapp.myaction")
        startActivityAndWait(intent)
    }
}
   

Menyiapkan aplikasi

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

<application ... >
    <!-- Profileable to enable Macrobenchmark profiling -->
    <!-- Suppress AndroidElementNotAllowed -->
    <profileable android:shell="true"/>
    ...
</application>

Konfigurasikan aplikasi benchmark seidentik mungkin dengan pengalaman pengguna. Siapkan sebagai tidak dapat di-debug dan sebaiknya dengan minifikasi aktif, yang akan meningkatkan performa. Hal ini biasanya dilakukan dengan membuat salinan benchmark varian release, yang akan memiliki performa yang sama, tetapi ditandatangani secara lokal dengan kunci debug:

buildTypes {
    benchmark {
        // duplicate any release build type settings for measurement accuracy,
        // such as "minifyEnabled" and "proguardFiles" in this block

        debuggable false
        signingConfig signingConfigs.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:

Menjalankan Macrobenchmark pada aktivitas internal memerlukan langkah tambahan. Untuk mengukur aktivitas internal exported=false, teruskan setupBlock ke MacrobenchmarkRule.measureRepeated() guna memilih kode agar dapat menjalankan pengukuran, lalu gunakan measureBlock untuk memanggil tindakan peluncuran atau scroll aktivitas yang sebenarnya untuk diukur.

Menyesuaikan macro benchmark

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 pada Android Nougat (API 24) dan yang lebih tinggi, menginstal Profil Dasar Pengukuran (jika tersedia), serta di Android Marshmallow (API 23) dan yang lebih rendah, sepenuhnya mengompilasi APK (yang merupakan perilaku sistem default).

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

Di Android Nougat (API 24) 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.

Startup

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

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

Scroll dan animasi

Tidak seperti kebanyakan pengujian UI Android, pengujian Macrobenchmark dijalankan dalam proses terpisah dari aplikasi itu sendiri. Hal ini diperlukan untuk mengaktifkan tindakan seperti menutup proses aplikasi dan mengompilasinya menggunakan perintah shell.

Anda dapat mendorong aplikasi menggunakan library UI Automator atau mekanisme lain yang dapat mengontrol aplikasi target dari proses pengujian. Pendekatan seperti Espresso atau ActivityScenario tidak akan berhasil karena diharapkan untuk berjalan dalam proses bersama aplikasi.

Contoh berikut menemukan RecyclerView menggunakan ID resource-nya, dan men-scroll ke bawah beberapa kali:

@Test
fun measureScroll() {
    benchmarkRule.measureRepeated(
        packageName = "mypackage.myapp",
        metrics = listOf(FrameTimingMetric()),
        iterations = 5,
        setupBlock = {
            // before starting to measure, navigate to the UI to be measured
            val intent = Intent()
            intent.action = ACTION
            startActivityAndWait(intent)
        }
    ) {
        val recycler = device.findObject(By.res("mypackage.myapp", "recycler_id"))
        // Set gesture margin to avoid triggering gesture nav
        // with input events from automation.
        recycler.setGestureMargin(device.displayWidth / 5)

        // Scroll down several times
        for (i in 1..10) {
            recycler.scroll(Direction.DOWN, 2f)
            device.waitForIdle()
        }
    }
}

Saat pengujian menentukan FrameTimingMetric, pengaturan waktu render frame dicatat dan dilaporkan sebagai ringkasan tingkat tinggi distribusi pengaturan waktu render frame: persentil ke-50, ke-90, ke-95, dan ke-99.

Benchmark Anda tidak perlu men-scroll UI. Sebagai gantinya, misalnya, aplikasi dapat menjalankan animasi. Ini juga tidak perlu menggunakan UI automator secara khusus; selama bingkai dihasilkan oleh sistem tampilan, yang mencakup bingkai yang dihasilkan oleh Compose, metrik performa dikumpulkan. Perlu diketahui bahwa mekanisme dalam proses seperti Espresso tidak akan berfungsi karena aplikasi harus diarahkan dari proses aplikasi pengujian.

Menjalankan macro benchmark

Jalankan pengujian dari dalam Android Studio untuk mengukur performa aplikasi di perangkat Anda. Perlu diketahui bahwa Anda harus menjalankan pengujian pada perangkat fisik, dan bukan emulator, karena emulator tidak menghasilkan angka performa yang mewakili pengalaman pengguna akhir.

Lihat bagian Benchmark dalam CI untuk mendapatkan informasi tentang cara menjalankan dan memantau benchmark dalam integrasi berkelanjutan.

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

$ ./gradlew :macrobenchmark:connectedCheck

Error konfigurasi

Jika aplikasi salah dikonfigurasi (dapat di-debug, atau tidak dapat dibuat profil), Macrobenchmark 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.

Memeriksa rekaman aktivitas

Setiap iterasi pengukuran menangkap rekaman 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 di bagian Jetpack Macrobenchmark dalam topik ini. Setelah rekaman aktivitas dimuat, Android Studio akan meminta Anda untuk memilih proses yang akan dianalisis. Pemilihan sudah diisi sebelumnya dengan proses aplikasi target:

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

Mengakses file rekaman aktivitas secara manual

Jika Anda menggunakan Android Studio versi lama (sebelum 2020.3.1), atau menggunakan alat Perfetto untuk menganalisis file rekaman aktivitas, Anda perlu melakukan langkah-langkah tambahan.

Pertama-tama, ambil file rekaman aktivitas dari perangkat:

# The following command pulls all files ending in .perfetto-trace from the directory
# hierarchy starting at the root /storage/emulated/0/Android.
$ adb shell find /storage/emulated/0/Android/ -name "*.perfetto-trace" \
    | tr -d '\r' | xargs -n1 adb pull

Perlu diketahui bahwa jalur file output mungkin berbeda jika Anda menyesuaikannya dengan argumen additionalTestOutputDir. Anda dapat mencari log jalur rekaman aktivitas di logcat untuk melihat tempat log tersebut ditulis. Contoh:

I PerfettoCapture: Writing to /storage/emulated/0/Android/data/androidx.benchmark.integration.macrobenchmark.test/cache/TrivialStartupBenchmark_startup[mode=COLD]_iter002.perfetto-trace.

Jika memanggil pengujian menggunakan command line Gradle (seperti ./gradlew macrobenchmark:connectedCheck), Anda dapat menyalin file hasil pengujian ke direktori output pengujian pada sistem host. Untuk melakukannya, tambahkan baris ini ke file gradle.properties project:

android.enableAdditionalTestOutput=true

File hasil dari pengujian akan ditampilkan di direktori build project seperti ini:

build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/<device-name>/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. Ini menunjukkan tampilan alat profiler yang ditampilkan di bagian sebelumnya.

Sebagai gantinya, Anda dapat memilih untuk menggunakan alat Perfetto. Perfetto memungkinkan Anda memeriksa semua proses yang terjadi di seluruh perangkat selama pelacakan, sementara CPU profiler Android Studio membatasi pemeriksaan pada satu proses.

Meningkatkan 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 cara membuat peristiwa rekaman aktivitas kustom lebih lanjut, lihat panduan Menentukan peristiwa kustom.

Benchmark dalam CI

Sangat umum untuk menjalankan pengujian di CI tanpa Gradle, atau secara lokal jika Anda menggunakan sistem build yang berbeda. Bagian ini menjelaskan cara mengonfigurasi Macrobenchmark untuk penggunaan CI pada runtime.

File hasil: JSON dan rekaman aktivitas

Macrobenchmark menghasilkan file JSON dan beberapa file rekaman aktivitas: satu per iterasi terukur untuk setiap loop MacrobenchmarkRule.measureRepeated.

Anda dapat menentukan tempat file ini ditulis dengan meneruskan argumen instrumentasi berikut pada runtime:

-e additionalTestOutputDir "device_path_you_can_write_to"

Perlu diketahui bahwa agar lebih mudah Anda dapat menentukan lokasi di /sdcard/, tetapi Anda harus memilih untuk tidak menggunakan penyimpanan dengan cakupan tertentu dengan menyetel requestLegacyExternalStorage ke true di modul Macrobenchmark:

<manifest ... >
  <application android:requestLegacyExternalStorage="true" ... >
    ...
  </application>
</manifest>

Atau, teruskan argumen instrumentasi guna melewati penyimpanan terbatas untuk pengujian:

-e no-isolated-storage 1

Contoh JSON

Berikut ini contoh output JSON untuk benchmark startup tunggal:

{
    "context": {
        "build": {
            "device": "walleye",
            "fingerprint": "google/walleye/walleye:10/QQ3A.200805.001/6578210:userdebug/dev-keys",
            "model": "Pixel 2",
            "version": {
                "sdk": 29
            }
        },
        "cpuCoreCount": 8,
        "cpuLocked": false,
        "cpuMaxFreqHz": 2457600000,
        "memTotalBytes": 3834605568,
        "sustainedPerformanceModeEnabled": false
    },
    "benchmarks": [
        {
            "name": "startup",
            "params": {},
            "className": "androidx.benchmark.integration.macrobenchmark.SampleStartupBenchmark",
            "totalRunTimeNs": 77969052767,
            "metrics": {
                "startupMs": {
                    "minimum": 228,
                    "maximum": 283,
                    "median": 242,
                    "runs": [
                        238,
                        283,
                        256,
                        228,
                        242
                    ]
                }
            },
            "warmupIterations": 3,
            "repeatIterations": 5,
            "thermalThrottleSleepSeconds": 0
        }
    ]
}

Referensi lainnya

Contoh project tersedia sebagai bagian dari repositori contoh performa/Android di GitHub.

Untuk panduan cara mendeteksi regresi performa, lihat Mengatasi Regresi dengan Benchmark dalam CI.

Masukan

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