Benchmark

Android Studio 内でコードのパフォーマンスを正確に測定します。
最新の更新 現在の安定版リリース 次のリリース候補 ベータ版リリース アルファ版リリース
2021 年 9 月 29 日 1.0.0 - - 1.1.0-alpha08

依存関係の宣言

Benchmark への依存関係を追加するには、Google の Maven リポジトリをプロジェクトに追加する必要があります。詳しくは、Google の Maven リポジトリをご覧ください。

アプリまたはモジュールの build.gradle ファイルに、必要なアーティファクトの依存関係を追加します。

Groovy

dependencies {
    androidTestImplementation "androidx.benchmark:benchmark-junit4:1.0.0"
}

android {
    ...
    defaultConfig {
        ...
        testInstrumentationRunner "androidx.benchmark.junit4.AndroidBenchmarkRunner"
    }
}

Kotlin

dependencies {
    androidTestImplementation("androidx.benchmark:benchmark-junit4:1.0.0")
}

android {
    ...
    defaultConfig {
        ...
        testInstrumentationRunner = "androidx.benchmark.junit4.AndroidBenchmarkRunner"
    }
}

Benchmark ライブラリには、ベンチマーク モジュールで使用する Gradle プラグインも用意されています。このプラグインは、モジュールのビルド設定のデフォルトを設定し、ベンチマーク出力のコピーをホストにセットアップし、./gradlew lockClocks タスクを提供します。

このプラグインを使用するには、最上位の build.gradle ファイルに次の classpath を含めてください。

Groovy

buildscript {
    repositories {
        google()
    }
    dependencies {
        classpath "androidx.benchmark:benchmark-gradle-plugin:1.0.0"
    }
}

Kotlin

buildscript {
    repositories {
        google()
    }
    dependencies {
        classpath("androidx.benchmark:benchmark-gradle-plugin:1.0.0")
    }
}

次に、プラグインをベンチマーク モジュールの build.gradle ファイルに適用します。

Groovy

apply plugin: "androidx.benchmark"

Kotlin

plugins {
    id("androidx.benchmark")
}

Macrobenchmark

プロジェクトで Macrobenchmark を使用するには、アプリまたはモジュールの build.gradle ファイルに次の依存関係を追加します。

Groovy

dependencies {
  androidTestImplementation "androidx.benchmark:benchmark-macro-junit4:1.1.0-alpha09"
}

Kotlin

dependencies {
  androidTestImplementation("androidx.benchmark:benchmark-macro-junit4:1.1.0-alpha09")
}

フィードバック

お寄せいただいたフィードバックは Jetpack 改善の参考にさせていただきます。新しい問題が見つかった場合や、このライブラリを改善するアイデアをお持ちの場合は、お知らせください。新しい問題を報告していただく前に、このライブラリの既存の問題をご確認ください。スターボタンをクリックすると、既存の問題に投票できます。

新しい問題を報告する

詳細については、Issue Tracker のドキュメントをご覧ください。

バージョン 1.1.0

バージョン 1.1.0-alpha08

2021 年 9 月 29 日

androidx.benchmark:benchmark-*:1.1.0-alpha08 がリリースされました。バージョン 1.1.0-alpha08 に含まれる commit については、こちらをご覧ください。

API の変更

  • マクロベンチマークのスクロールを有効にしてAPI 23 に遡れるようにします。（If39c2、b/183129298）
  • 反復処理ごとの複数のサンプルのパーセンタイルに焦点を当て、新しいタイプのサンプリングされた指標を UI と JSON 出力に追加します。（I56247、b/199940612）
  • ベンチマーク ライブラリ全体で浮動小数点数指標に切り替えます（Studio UI では切り捨てられます）。（I69249、b/197008210）

バージョン 1.1.0-alpha07

2021 年 9 月 1 日

androidx.benchmark:benchmark-*:1.1.0-alpha07 がリリースされました。バージョン 1.1.0-alpha07 に含まれる commit については、こちらをご覧ください。

API の変更

  • 最小 API を 21 に引き上げ、今後サポートされることが想定される最小 API レベルを反映しました。現在サポートされている最小 API は、RequiredApi() を介して引き続き伝えられます。現在は 29 です。（I440d6、b/183129298）

バグの修正

  • ベースライン プロファイルを使用するアプリで、CompilationMode.BaselineProfile を使って MacroBenchmark を簡単に実行できるように、ProfileInstaller を修正しました。（I42657、b/196074999）注: androidx.profileinstaller:profileinstaller:1.1.0-alpha04 以降への更新も必要です。
  • StartupMode.COLD と CompilationMode.None のベンチマークの安定性が向上しました。（I770cd、b/196074999）

バージョン 1.1.0-alpha06

2021 年 8 月 18 日

androidx.benchmark:benchmark-*:1.1.0-alpha06 がリリースされました。バージョン 1.1.0-alpha06 に含まれる commit については、こちらをご覧ください。

API の変更

  • ローカルでテスト / プロファイリングするときに反復回数を手動でオーバーライドできるように、androidx.benchmark.iterations インストルメンテーション引数を追加しました。（6188be、b/194137879）

バグの修正

  • API 29 以降で、デフォルトのサンプリング プロファイラとして Simpleperf に切り替えました。（Ic4b34、b/158303822）

既知の問題

  • CompilationMode.BaselineProfile は開発中です。現時点ではプロファイルの良さを判断するために使用しないでください。

バージョン 1.1.0-alpha05

2021 年 8 月 4 日

androidx.benchmark:benchmark-*:1.1.0-alpha05 がリリースされました。バージョン 1.1.0-alpha05 に含まれる commit については、こちらをご覧ください。

散発的なクラッシュにより、1.1.0-alpha04 はリリース前にキャンセルされました。b/193827052

API の変更

  • startActivityAndWait が am start で起動を呼び出すように切り替えられました。これにより、インテント Parcelable がサポートされなくなりますが、各測定イテレーションの時間が約 5 秒短縮されます。（I5a6f5、b/192009149）

バグの修正

  • サーマル スロットル検出の積極性を下げ、スロットルが頻繁に検出される場合はベースラインを再計算します。（I7327b）
  • Android S ベータ版で動作するように FrameTimingMetric を修正しました。（Ib60cc、b/193260119）
  • EmptyActivity を使用して、ターゲット アプリを強制停止状態から解除し、CompilationMode.BaselineProfile のサポートを改善します。（Id7cac、b/192084204）
  • プラットフォーム標準に合わせてトレース ファイル拡張子を .perfetto-trace に変更しました。（I4c236、b/174663039）
  • StartupTimingMetric は、アプリケーションのレンダリングが完了するまでの時間を測定する「fullyDrawnMs」指標を出力するようになりました。アプリに対してこの指標を定義するには、初期リストアイテムが DB やネットワークから読み込まれたときなど、初期コンテンツの準備ができたときに Activity.reportFullyDrawn を呼び出します（reportFullyDrawn メソッドは、ComponentActivity のビルド バージョン チェックなしで使用可能）。テストは指標を取得するのに十分な時間実行する必要があります（startActivityAndWait は reportFullyDrawn を待機しません）。（If1141、b/179176560）
  • トレースへの Ui メタデータの追加にかかるコストを 50 ミリ秒以上削減します。（Ic8390、b/193923003）
  • トレースを停止する際のポーリング頻度を大幅に増やしました。これにより、たとえば起動ベンチマークのランタイムを 30% 以上短縮できます。（Idfbc1、b/193723768）

バージョン 1.1.0-alpha03

2021 年 6 月 16 日

androidx.benchmark:benchmark-*:1.1.0-alpha03 がリリースされました。バージョン 1.1.0-alpha03 に含まれる commit については、こちらをご覧ください。

新機能

バグの修正

  • ベンチマーク エラーを抑制するための Gradle サンプルコードが更新され、サポートが終了していない API（その構文は .gradle.kts ユーザーもサポートします）を使用するようになりました。

    例: 

    testInstrumentationRunnerArguments["androidx.benchmark.suppressErrors"] = "EMULATOR,LOW-BATTERY"

バージョン 1.1.0-alpha02

2021 年 5 月 18 日

Benchmark バージョン 1.1.0-alpha02 では、ベンチマーク測定のための主要なコンポーネントである Macrobenchmark を導入しました。Macrobenchmark は、CPU ループを測定できるベンチマークを提供するだけでなく、アプリ全体の操作（起動やスクロールなど）の測定、トレースのキャプチャにも使用できます。詳しくは、ライブラリのドキュメントをご覧ください。

androidx.benchmark:benchmark-*:1.1.0-alpha02 がリリースされました。バージョン 1.1.0-alpha02 に含まれる commit については、こちらをご覧ください。

新機能

Macrobenchmark のアーティファクトを追加しました（androidx.benchmark:benchmark-macro-junit4 と androidx.benchmark:benchmark-macro）。

  • ローカルまたは CI で、アプリの起動、スクロールまたはアニメーションのパフォーマンス指標をキャプチャします。
  • Android Studio 内からトレースをキャプチャして検査します。

バグの修正

  • Android 12 の出力ディレクトリにおけるシェル権限の問題を解決しました（注 - 影響を受けるデバイスで引き続き出力ファイルをキャプチャするには、Android Gradle プラグインを Android 7.0.0 Canary に、Android Studio を Arctic Fox（2020.3.1）に更新する必要があります）。（Icb039）
  • BenchmarkPlugin の構成キャッシュのサポートを追加しました。（6be1c1、b/159804788）
  • ファイル出力を簡素化しました。デフォルトでは、requestLegacyExternalStorage=true を必要としないディレクトリで有効になっています。（8b5a4d、b/172376362）
  • JIT スレッドが存在しないプラットフォーム バージョンで JIT スレッドが見つからないという logcat 警告をライブラリが出力する問題を修正しました。（I9cc63、b/161847393）
  • デバイス読み取りの最大周波数に関する問題を修正しました。（I55c7a）

バージョン 1.1.0-alpha01

2020 年 6 月 10 日

androidx.benchmark:benchmark-common:1.1.0-alpha01、androidx.benchmark:benchmark-gradle-plugin:1.1.0-alpha01、androidx.benchmark:benchmark-junit4:1.1.0-alpha01 がリリースされました。バージョン 1.1.0-alpha01 に含まれるコミットについては、こちらをご覧ください。

1.1 の新機能

  • 割り当て指標 - ベンチマークが、ウォームアップとタイミングの後に追加のフェーズを実行し、割り当て数をキャプチャするようになりました。割り当てによって、古いバージョンのプラットフォームでパフォーマンスの問題が発生することがあります（クロックをロックした Nexus5X で測定したところ、O での 140 ns が M では 8 ns になりました）。この指標は、Android Studio コンソールの出力に表示されます。
  • プロファイリングのサポート - ベンチマーク実行用のプロファイリング データをキャプチャして、コードの実行速度が遅い理由を調べられるようになりました。ベンチマークでは、メソッド トレースのキャプチャ、または ART からのメソッド サンプリングのキャプチャがサポートされます。これらのファイルは、[ファイル] > [開く] を使用して、Android Studio 内の Profiler で検査できます。
  • Benchmark Gradle プラグインで、設定を簡単にするデフォルトが提供されるようになりました。
    • testBuildType は、コード カバレッジが組み込まれた依存関係を使用しないように、デフォルトでリリースに設定されています。リリースの buildType はデフォルトの buildType としても構成されています。これにより、Android Studio でプロジェクトを初めて開くときに正しいビルド バリアントが自動的に選択されます。（b/138808399）
    • デフォルトの署名設定として signingConfig.debug が使用されます（b/153583269）

** バグの修正 **

  • 各ベンチマークの最初の測定値が他よりも人為的に高かった、ウォームアップ遷移のオーバーヘッドを大幅に削減しました。この問題は、非常に小さなベンチマーク（1 マイクロ秒以下）の方が顕著でした。（b/142058671）
  • コマンドラインから実行した場合に、ベンチマークごとに InstrumentationResultParser エラーが表示される問題を修正しました。（I64988, b/154248456）

既知の問題

  • コマンドラインによるベンチマークの gradle 呼び出しで、結果が直接出力されません。この問題を回避するには、Studio を介して実行するか、JSON 出力ファイルを解析して結果を取得します。
  • ベンチマーク レポートで、applicationId が「android」または「download」（大文字と小文字を区別しない）で終わるアプリがインストールされているデバイスからレポートを取得できません。この問題が発生した場合は、Android Gradle プラグインを 4.2-alpha01 以降にアップグレードする必要があります。

バージョン 1.0.0

Benchmark バージョン 1.0.0

2019 年 11 月 20 日

androidx.benchmark:benchmark-common:1.0.0、androidx.benchmark:benchmark-gradle-plugin:1.0.0、androidx.benchmark:benchmark-junit4:1.0.0 がリリースされました。1.0.0-rc01 からの変更はありません。バージョン 1.0.0 に含まれるコミットについては、こちらをご覧ください。

1.0.0 の主な機能

Benchmark ライブラリを使用すると、アプリコードのパフォーマンス ベンチマークを作成して結果をすばやく取得できます。

ビルドとランタイム設定の問題を防ぎ、デバイスのパフォーマンスを安定させ、正確で一貫性のある測定を実現します。Android Studio での直接操作、または継続的インテグレーションによりベンチマークを実行して、コードのパフォーマンスを時系列で観察し、回帰を防ぎます。

主な機能は次のとおりです。

  • クロックの安定
  • スレッドの自動優先設定
  • RecyclerView サンプルなどで UI パフォーマンス テストをサポート
  • JIT 対応のウォームアップとループ
  • 後処理用に JSON 形式でベンチマーク出力

バージョン 1.0.0-rc01

2019 年 10 月 23 日

androidx.benchmark:benchmark-common:1.0.0-rc01、androidx.benchmark:benchmark-gradle-plugin:1.0.0-rc01、androidx.benchmark:benchmark-junit4:1.0.0-rc01 がリリースされました。バージョン 1.0.0-rc01 に含まれるコミットについては、こちらをご覧ください。

新機能

  • ベンチマークに systrace トレースを追加

バグの修正

  • 優先度の低下により JIT がウォームアップ前に終了せず、指標が不安定である問題を修正（b/140773023）
  • Android Gradle プラグイン 3.5 および 3.6 での JSON 出力ディレクトリの統合

バージョン 1.0.0-beta01

2019 年 10 月 9 日

androidx.benchmark:benchmark-common:1.0.0-beta01、androidx.benchmark:benchmark-gradle-plugin:1.0.0-beta01、androidx.benchmark:benchmark-junit4:1.0.0-beta01 がリリースされました。バージョン 1.0.0-beta01 に含まれるコミットについては、こちらをご覧ください。

新機能

  • 各ウォームアップの前にガベージ コレクションを実行して、次々にベンチマークを行う際に発生するメモリリークによるメモリ圧迫を軽減（b/140895105）

バグの修正

  • androidx.annotation:android-experimental-lint の依存関係を追加。これにより、試験運用版 API を使用しない場合に Java コードで正しく lint エラーが生成されます。Kotlin で呼び出す際に Kotlin の試験運用版アノテーションで提供されるものと同様のエラーになります。
  • Android Gradle Plugin（AGP）3.6 の出力に対して、additionalTestOutputDir インストルメンテーション引数の使用を正しく検出するようになりました。これにより、AGP がデータコピーを処理するタイミングを把握できます。
  • JSON でクロック周波数が検出されない問題を修正し、正しく -1 が出力されるようになりました。（b/141945670）

バージョン 1.0.0-alpha06

2019 年 9 月 18 日

androidx.benchmark:benchmark-common:1.0.0-alpha06、androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha06、androidx.benchmark:benchmark-junit4:1.0.0-alpha06 がリリースされました。バージョン 1.0.0-alpha06 に含まれるコミットについては、こちらをご覧ください。

新機能

  • テストランナーの古いパッケージの誤使用に対してチェックを追加しました。これで、より参考になるエラー メッセージが表示されるようになりました。

API の変更

  • 試験運用版アノテーション ExperimentalAnnotationReport が正しく public になりました。試験運用版 BenchmarkState#report API を使用するには、このアノテーションが必要となりました。

バージョン 1.0.0-alpha05

2019 年 9 月 5 日

androidx.benchmark:benchmark-common:1.0.0-alpha05、androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha05、androidx.benchmark:benchmark-junit4:1.0.0-alpha05 がリリースされました。このバージョンに含まれる commit については、こちらをご覧ください。

API の変更

  • BenchmarkState.reportData API は試験運用となりました。

バグの修正

  • デバイスに cut または expr シェル ユーティリティがないと clock-locking スクリプトが失敗する問題を修正しました。
  • ./gradlew lockClocks タスクの問題を修正しました。-c フラグをサポートしていない古いバージョンの su ユーティリティでルート権限を取得したデバイスでハングアップしていました。

バージョン 1.0.0-alpha04

2019 年 8 月 7 日

androidx.benchmark:benchmark-common:1.0.0-alpha04、androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha04、androidx.benchmark:benchmark-junit4:1.0.0-alpha04 がリリースされました。このバージョンに含まれる commit については、こちらをご覧ください。

異なるビルドシステム（Bazel や Buck など）での使用と CI での実行の両方で、Gradle なしで Benchmark ライブラリを使用する方法についての新しいドキュメントも追加されました。詳細については、Gradle を使用せずにベンチマークを作成すると継続的インテグレーションでベンチマークを実行するをご覧ください。

新機能

  • Gradle プラグイン
    • テスト カバレッジが自動的に無効になり、デフォルトで AndroidBenchmarkRunner が設定されるようになりました。（b/138374050）
    • ベンチマーク実行時と AGP 3.6+ 使用時の、新しい AGP ベースのデータコピーのサポートを追加しました。
  • JSON 形式の追加
    • ベンチマーク テストの合計実行時間を出力（b/133147694）
    • 名前文字列（@Parameters(name = "size={0},depth={1}") など）を使用する @Parameterized ベンチマークが、JSON 出力でベンチマークごとにパラメータ名と値を出力するようになりました。（b/132578772）
  • ドライラン モード（b/138785848）
    • 測定値をキャプチャせずにエラー / クラッシュを確認できるように、各ベンチマーク ループを 1 回だけ実行する「ドライラン」モードを追加しました。これはたとえば、送信前にベンチマークをすばやく実行して、障害がないことを確認する場合などに便利です。

API の変更

  • モジュール構造が変更され、ライブラリが分割されました。（b/138451391）
    • benchmark:benchmark-junit4 には JUnit 依存関係を持つ AndroidBenchmarkRunner および BenchmarkRule クラスが含まれます。これらはいずれも androidx.benchmark.junit4 パッケージに移動されました。
    • benchmark:benchmark-common には、BenchmarkState API を含む残りのロジックが含まれます。
    • この分割により、ライブラリは今後 JUnit4 API なしでベンチマークをサポートできるようになります。
  • 構成の警告はエラーとして扱われるようになりました。そのため、テストはクラッシュします。（b/137653596）
    • この変更の目的は、特に CI で正確な測定を奨励することです。
    • これらのエラーは、インストルメンテーション引数を使用して警告に戻すことができます。例: -e androidx.benchmark.suppressErrors "DEBUGGABLE,LOW_BATTERY"

バグの修正

  • Q デバイス上の外部ストレージへの書き込み時にエラーが発生すると、問題を解決する方法が提案されるとともに、わかりやすいメッセージが表示されます。
  • 画面がオフのときに失敗するのではなく、ベンチマークの実行中に画面が自動的にオンになります。

外部寄与

  • JSON 出力の改善と画面オフの問題の修正に寄与した Sergey Zakharov 氏に感謝いたします。

バージョン 1.0.0-alpha03

2019 年 7 月 2 日

androidx.benchmark:benchmark:1.0.0-alpha03 と androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha03 がリリースされました。このバージョンに含まれる commit については、こちらをご覧ください。

新機能

  • ベンチマークごとのサーマル スロットリングによるスリープ期間を完全な JSON レポートで公開

バグの修正

  • Gradle プラグインは、Android プラグインと Android ブロックの後に適用する必要がなくなりました。
  • 対象範囲別ストレージを使用した Android 10 デバイスでのベンチマーク レポートのサポートを追加

バージョン 1.0.0-alpha02

2019 年 6 月 6 日

androidx.benchmark:1.0.0-alpha02 と androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha02 がリリースされました。このバージョンに含まれるコミットについては、こちらをご覧ください。

JSON スキーマが API として扱われていることにご注意ください。他の API と同じ安定性制約に従うことが予定されています。安定版は（非常にまれな例外を除いて）元のベータ版であり、最終リリースで修正され、マイナー リリースでは追加のみ、メジャー リリースでは変更 / 削除のみが行われます。

API の変更

  • JSON スキーマをオーバーホールしました。JSON スキーマに対するこれ以降の変更は、追加に限定される可能性があります。

    • 将来的に追加の指標グループをサポートできるように結果オブジェクトの構造を再編成しました（b/132713021）
    • テスト実行コンテキスト情報（デバイスとビルドの情報や、クロックがロックされているかどうかなど）を、最上位のオブジェクトに追加しました（b/132711920）
    • 時間指標の名前に「ns」が含まれるようになりました（b/132714527）
    • 報告される各指標にさらなる統計情報（最大値、中央値、最小値）を追加し、簡略化された「ナノ」サマリー統計情報を削除しました（b/132713851）

  • XML 出力を削除しました（b/132714414）

  • サーマル スロットルの検出を BenchmarkState.reportData API から削除しました（b/132887006）

バグの修正

  • 最近の OS が搭載された一部のデバイスで ./gradlew lockClocks が安定しない問題を修正しました（b/133424037）
  • エミュレータのスロットル検出を無効化しました（b/132880807）

バージョン 1.0.0-alpha01

2019 年 5 月 7 日

androidx.benchmark:benchmark:1.0.0-alpha01 がリリースされました。このバージョンに含まれるコミットについては、こちらをご覧ください。