Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Kode aplikasi tolok ukur

Library Jetpack Benchmark memungkinkan Anda mengukur dengan cepat kode berbasis Java atau Kotlin dari dalam Android Studio. Library tersebut menangani pemanasan, mengukur performa kode, dan menampilkan hasil tolok ukur ke konsol Android Studio.

Kasus penggunaan mencakup men-scroll RecyclerView, meluaskan hierarki View non-trivial, dan menjalankan kueri database.

Anda dapat menggunakan library dalam lingkungan continuous integration (CI), seperti yang dijelaskan dalam Menjalankan tolok ukur dalam Continuous Integration.

Jika belum mengadopsi AndroidX dalam project yang ingin diukur, lihat Melakukan migrasi project yang ada menggunakan Android Studio.

Panduan memulai

Bagian ini memberikan serangkaian langkah cepat dalam mengukur tanpa harus memindahkan kode ke dalam modul. Karena langkah-langkahnya melibatkan penonaktifan proses debug untuk hasil performa yang akurat, Anda tidak akan melakukan perubahan pada sistem kontrol sumber, tetapi hal tersebut masih dapat membantu ketika ingin menjalankan pengukuran satu kali.

Untuk menjalankan tolok ukur satu kali dengan cepat, lakukan hal berikut:

  1. Tambahkan library ke file build.gradle modul Anda:

    project_root/module_dir/build.gradle

        dependencies {
            androidTestImplementation "androidx.benchmark:benchmark-junit4:1.0.0-beta01"
        }
        
  2. Untuk menonaktifkan proses debug di manifes pengujian, update elemen <application> untuk menonaktifkan paksa proses debug sementara seperti berikut:

    project_root/module_dir/src/androidTest/AndroidManifest.xml

    <!-- Important: disable debuggable for accurate performance results -->
        <application
            android:debuggable="false"
            tools:ignore="HardcodedDebugMode"
            tools:replace="android:debuggable"/>
        
  3. Untuk menambahkan tolok ukur, tambahkan instance dari BenchmarkRule dalam file pengujian di direktori androidTest. Untuk informasi menulis tolok ukur selengkapnya, lihat Menulis tolok ukur.

    Cuplikan kode berikut ini menunjukkan cara menambahkan tolok ukur ke pengujian JUnit:

    Kotlin

        @RunWith(AndroidJUnit4::class)
        class MyBenchmark {
            @get:Rule
            val benchmarkRule = BenchmarkRule()
    
            @Test
            fun benchmarkSomeWork() = benchmarkRule.measureRepeated {
                doSomeWork()
            }
        }
        

    Java

        @RunWith(AndroidJUnit4.class)
        class MyBenchmark {
            @Rule
            public BenchmarkRule benchmarkRule = new BenchmarkRule();
    
            @Test
            public void myBenchmark() {
                final BenchmarkState state = benchmarkRule.getState();
                while (state.keepRunning()) {
                    doSomeWork();
                }
            }
        }
        

Apa saja yang perlu diukur

Tolok ukur sangat berguna untuk tugas CPU yang dijalankan berkali-kali di aplikasi Anda. Contoh yang baik adalah men-scroll RecyclerView, konversi/pemrosesan data, dan potongan kode yang digunakan berulang kali.

Jenis kode yang lain lebih sulit diukur dengan tolok ukur. Karena tolok ukur berjalan dalam sebuah loop, semua kode yang jarang dijalankan atau berperforma berbeda ketika dipanggil beberapa kali, mungkin tidak sesuai untuk tolok ukur.

Menyimpan ke cache

Coba hindari pengukuran hanya cache. Misalnya, tolok ukur tata letak tampilan kustom mungkin hanya mengukur performa cache tata letak. Untuk menghindarinya, Anda dapat meneruskan parameter tata letak yang berbeda di setiap loop. Dalam kasus lain, seperti saat mengukur performa sistem file, tindakan ini mungkin sulit karena OS menyimpan cache sistem file sementara dalam sebuah loop.

Kode yang jarang dijalankan

Kode yang dijalankan satu kali selama startup aplikasi kecil kemungkinannya untuk dikompilasi dengan JIT dari Android Runtime (ART). Karena itu, mengukur kode ini saat berjalan dalam sebuah loop bukanlah cara yang realistis untuk mengetahui performanya.

Untuk kode semacam ini, kami merekomendasikan untuk melacak atau membuat profil kode di aplikasi Anda. Perlu diperhatikan ini tidak berarti bahwa kode tidak dapat diukur dalam jalur startup, tetapi Anda harus memilih kode yang dijalankan dalam sebuah loop, dan dengan demikian akan meningkatkan kemungkinan untuk dikompilasi dengan JIT.

Penyiapan project lengkap

Guna menyiapkan tolok ukur untuk tolok ukur reguler bukan tolok ukur satu kali, Anda harus memisahkan tolok ukur ke dalam modulnya masing-masing. Tindakan ini memastikan konfigurasi modul, seperti menetapkan debuggable ke false, terpisah dari pengujian reguler.

Untuk melakukannya, Anda harus menyelesaikan tugas berikut:

  • Masukkan kode dan resource yang ingin Anda ukur ke dalam modul library jika belum ada.

  • Tambahkan modul library baru untuk menyimpan tolok ukur itu sendiri.

Contoh kami menunjukkan bagaimana menyiapkan project dengan cara tersebut.

Menyiapkan properti Android Studio

Jika menggunakan Android Studio 3.5, Anda harus menetapkan properti Android Studio secara manual untuk mengaktifkan dukungan wizard modul tolok ukur. Tindakan ini tidak diperlukan untuk Android Studio 3.6 atau yang lebih tinggi.

Untuk mengaktifkan template Android Studio pada tolok ukur, lakukan hal berikut:

  1. Di Android Studio 3.5, klik Help > Edit Custom Properties.

  2. Tambahkan baris berikut ke file yang terbuka:

    npw.benchmark.template.module=true

  3. Simpan dan tutup file tersebut.

  4. Mulai ulang Android Studio.

Membuat modul baru

Template modul tolok ukur otomatis mengonfigurasi setelan untuk pengukuran.

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

  1. Klik kanan project atau modul Anda, kemudian pilih New > Module.

  2. Pilih Benchmark Module lalu klik Next.

    Gambar 1. Modul tolok ukur

  3. Masukkan nama modul, pilih bahasa, dan klik Finish.

    Modul dibuat dan telah dikonfigurasi sebelumnya untuk tolok ukur, dengan menambahkan direktori tolok ukur serta debuggable ditetapkan ke false.

Menulis tolok ukur

Tolok ukur adalah pengujian instrumentasi standar. Untuk membuat tolok ukur, gunakan class BenchmarkRule yang disediakan oleh library. Untuk melakukan tolok ukur aktivitas, gunakan ActivityTestRule atau ActivityScenarioRule. Untuk melakukan tolok ukur kode UI, gunakan @UiThreadTest.

Kode berikut menunjukkan tolok ukur contoh:

Kotlin

    @RunWith(AndroidJUnit4::class)
    class ViewBenchmark {
        @get:Rule
        val benchmarkRule = BenchmarkRule()

        @Test
        fun simpleViewInflate() {
            val context = ApplicationProvider.getApplicationContext()
            val inflater = LayoutInflater.from(context)
            val root = FrameLayout(context)

            benchmarkRule.keepRunning {
                inflater.inflate(R.layout.test_simple_view, root, false)
            }
        }
    }
    

Java

    @RunWith(AndroidJUnit4::class)
    public class ViewBenchmark {
        @Rule
        public BenchmarkRule benchmarkRule = new BenchmarkRule();

        @Test
        public void simpleViewInflate() {
            Context context = ApplicationProvider.getApplicationContext();
            final BenchmarkState state = benchmarkRule.getState();
            LayoutInflater inflater = LayoutInflater.from(context);
            FrameLayout root = new FrameLayout(context);

            while (state.keepRunning()) {
                inflater.inflate(R.layout.test_simple_view, root, false);
            }
        }
    }
    

Anda dapat menonaktifkan pengaturan waktu untuk bagian kode yang tidak ingin diukur, seperti yang ditunjukkan pada contoh kode berikut:

Kotlin

    @Test
    fun bitmapProcessing() = benchmarkRule.measureRepeated {
        val input: Bitmap = runWithTimingDisabled { constructTestBitmap() }
        processBitmap(input)
    }
    

Java

    @Test
    public void bitmapProcessing() {
        final BenchmarkState state = benchmarkRule.getState();
        while (state.keepRunning()) {
            state.pauseTiming();
            Bitmap input = constructTestBitmap();
            state.resumeTiming();

            processBitmap(input);
        }
    }
    

Untuk informasi tentang menjalankan tolok ukur, lihat Menjalankan tolok ukur.

Menjalankan tolok ukur

Di Android Studio, jalankan tolok ukur seperti halnya @Test. Di Android Studio 3.4 dan yang lebih tinggi, Anda dapat melihat output yang dikirim ke konsol.

Untuk menjalankan tolok ukur, dalam modul, buka benchmark/src/androidTest lalu tekan Control+Shift+F10 (Command+Shift+R di Mac). Hasil tolok ukur akan muncul di konsol seperti yang ditunjukkan pada Gambar 2:

Output tolok ukur di Android Studio

Gambar 2. Output tolok ukur di Android Studio

Dari command line, jalankan connectedCheck reguler:

./gradlew benchmark:connectedCheck
    

Mengumpulkan data

Laporan tolok ukur lengkap dengan metrik tambahan dan informasi perangkat tersedia dalam format JSON.

Plugin Gradle androidx.benchmark mengaktifkan output JSON secara default. Untuk mengaktifkan output JSON secara manual di lingkungan build non-Gradle, teruskan argumen instrumentasi, androidx.benchmark.output.enable, lalu tetapkan ke true.

Berikut adalah contoh menggunakan perintah adb shell am instrument:

    adb shell am instrument -w -e "androidx.benchmark.output.enable" "true" com.android.foo/androidx.benchmark.junit4.AndroidBenchmarkRunner
    

Secara default, laporan JSON ditulis ke disk di perangkat dalam folder download bersama eksternal APK pengujian, yang biasanya terletak di:

    /storage/emulated/0/Download/app_id-benchmarkData.json
    

Anda dapat mengonfigurasi lokasi tempat laporan tolok ukur disimpan pada perangkat menggunakan argumen instrumentasi additionalTestOutputDir.

    adb shell am instrument -w -e "androidx.benchmark.output.enable" "true" -e "additionalTestOutputDir" "/path_to_a_directory_on_device_test_has_write_permissions_to/" com.android.foo/androidx.benchmark.junit4.AndroidBenchmarkRunner
    

Laporan JSON akan 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/app_id-benchmarkData.json
    

Android Gradle Plugin 3.6 dan yang lebih baru

Saat menjalankan tolok ukur dari command line dengan Gradle, project yang menggunakan Android Gradle Plugin 3.6 dan yang lebih tinggi dapat menambahkan flag berikut ke file gradle.properties project:

    android.enableAdditionalTestOutput=true
    

Tindakan ini akan mengaktifkan fitur Android Gradle Plugin eksperimental untuk mengambil laporan tolok ukur dari perangkat yang menjalankan API 16 dan yang lebih tinggi.

Android Gradle Plugin 3.5 dan yang lebih lama

Bagi pengguna Android Gradle Plugin versi yang lebih lama, plugin Gradle androidx.benchmark menangani penyalinan laporan tolok ukur JSON dari perangkat ke host.

Saat menggunakan AGP 3.5 atau yang lebih lama dan menargetkan API level 29 atau yang lebih tinggi, Anda harus menambahkan flag ke manifes Android di direktori androidTest dari tolok ukur untuk mengaktifkan perilaku penyimpanan eksternal lama. Lihat Memilih tidak ikut dari tampilan terfilter untuk informasi selengkapnya tentang memilih tidak ikut dari penyimpanan terbatas.

    <manifest ... >
      <!-- This attribute is "false" by default on apps targeting Android 10. -->
      <application android:requestLegacyExternalStorage="true" ... >
        ...
      </application>
    </manifest>
    

Stabilitas frekuensi CPU

Frekuensi CPU pada perangkat seluler berubah secara dinamis dari kondisi tinggi (untuk performa) ke kondisi rendah (untuk menghemat daya, atau saat perangkat menjadi panas). Frekuensi yang bervariasi ini dapat membuat hasil tolok ukur sangat bervariasi, sehingga library memberikan cara untuk mengatasi masalah ini.

Mengunci frekuensi CPU (membutuhkan root)

Mengunci frekuensi CPU adalah cara terbaik untuk mendapatkan performa yang stabil. Cara ini memastikan bahwa frekuensi CPU tidak terlalu tinggi sehingga membuat panas perangkat, atau rendah jika tolok ukur tidak sepenuhnya menggunakan CPU. Meskipun ini adalah cara terbaik untuk memastikan performa yang stabil, sebagian besar perangkat tidak mendukungnya karena memerlukan root adb.

Untuk mengunci frekuensi CPU, tambahkan plugin pembantu yang disediakan ke classpath project level teratas pada file build.gradle utama:

buildscript {
        ...
        dependencies {
            ...
            classpath "androidx.benchmark:benchmark-gradle-plugin:1.0.0-beta01"
        }
    }
    

Terapkan plugin di build.gradle modul yang menjadi tolok ukur Anda:

apply plugin: com.android.app
    apply plugin: androidx.benchmark
    ...
    

Tindakan ini akan menambahkan tugas Gradle tolok ukur ke project Anda, termasuk ./gradlew lockClocks dan ./gradlew unlockClocks. Gunakan tugas ini untuk mengunci dan membuka kunci CPU perangkat menggunakan adb.

Jika memiliki beberapa perangkat yang terlihat oleh adb, gunakan variabel lingkungan ANDROID_SERIAL untuk menentukan perangkat mana saja yang harus dijalankan oleh tugas Gradle:

    ANDROID_SERIAL=device-id-from-adb-devices ./gradlew lockClocks
    

Mode performa berkelanjutan

Window.setSustainedPerformanceMode() adalah fitur yang didukung oleh beberapa perangkat yang memungkinkan aplikasi memilih frekuensi CPU maksimal yang lebih rendah. Saat berjalan di perangkat yang didukung, library Benchmark menggunakan kombinasi API ini dan meluncurkan aktivitasnya sendiri untuk mencegah penurunan frekuensi karena panas dan menstabilkan hasil.

Fungsionalitas ini diaktifkan secara default oleh testInstrumentationRunner yang disetel oleh plugin Gradle. Jika ingin menggunakan runner kustom, Anda dapat membuat subclass AndroidBenchmarkRunner dan menggunakannya sebagai testInstrumentationRunner.

Runner meluncurkan aktivitas layar penuh buram untuk memastikan bahwa tolok ukur berjalan di latar depan dan tidak ada aplikasi lain yang menggambar.

Penjedaan eksekusi otomatis

Jika penguncian frekuensi CPU atau performa berkelanjutan digunakan, library akan otomatis melakukan deteksi penurunan frekuensi karena panas. Jika diaktifkan, tolok ukur internal akan berjalan secara berkala untuk menentukan kapan suhu perangkat cukup tinggi yang akan menurunkan performa CPU. Ketika penurunan performa CPU terdeteksi, library akan menjeda eksekusi untuk membiarkan perangkat menjadi dingin, dan mencoba kembali tolok ukur saat ini.

Error Konfigurasi

Library mendeteksi kondisi berikut guna memastikan project dan lingkungan Anda telah disiapkan untuk performa akurat rilis:

  • Debuggable disetel ke false.
  • Perangkat fisik, bukan emulator, sedang digunakan.
  • Frekuensi CPU terkunci jika perangkat di-root.
  • Tingkat daya baterai di perangkat memadai.

Jika salah satu pemeriksaan di atas gagal, tolok ukur akan memberikan pesan error untuk mencegah pengukuran yang tidak akurat.

Untuk mengubah error tersebut menjadi peringatan, dan mencegahnya memberikan pesan error sehingga menghentikan tolok ukur, teruskan jenis error yang ingin Anda ubah dalam daftar yang dipisahkan koma ke argumen instrumentasi androidx.benchmark.suppressErrors:

    adb shell am instrument -w -e "androidx.benchmark.suppressErrors" "DEBUGGABLE" com.android.foo/androidx.benchmark.junit4.AndroidBenchmarkRunner
    

Yang dapat Anda tetapkan di Gradle sebagai berikut:

    android {
        defaultConfig {
            testInstrumentationRunnerArgument 'androidx.benchmark.suppressErrors', 'DEBUGGABLE'
        }
    }
    

Perhatikan bahwa mengubah error memungkinkan tolok ukur berjalan dalam keadaan yang tidak terkonfigurasi dengan benar, tetapi output dari tolok ukur akan secara sengaja dirusak dengan menambahkan nama pengujian dengan error tersebut. Itu berarti, menjalankan tolok ukur yang dapat di-debug dengan penggantian seperti di atas akan menambahkan nama pengujian dengan DEBUGGABLE_.

Contoh tolok ukur

Kode tolok ukur contoh tersedia di project berikut:

Project contoh meliputi:

  • BenchmarkSample: ini adalah contoh mandiri, yang menunjukkan cara menggunakan modul tolok ukur untuk mengukur kode dan UI.

  • PagingWithNetworkSample : Contoh Komponen Arsitektur Android, yang menunjukkan cara mengukur performa RecyclerView.

  • WorkManagerSample: Contoh Komponen Arsitektur Android, yang menunjukkan cara mengukur pekerja WorkManager.

Memberikan masukan

Untuk melaporkan masalah atau mengirimkan permintaan fitur ketika menggunakan tolok ukur, lihat pelacak masalah publik.