Benchmark

API リファレンス
androidx.benchmark

Android Studio 内でコードのパフォーマンスを正確に測定します。

最新の更新	現在の安定版リリース	次のリリース候補	ベータ版リリース	アルファ版リリース
2020 年 6 月 10 日	1.0.0	-	-	1.1.0-alpha01

依存関係の宣言

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

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

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

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

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

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

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

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

apply plugin: "androidx.benchmark"

フィードバック

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

新しい問題を報告する

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

バージョン 1.1.0

バージョン 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 がリリースされました。このバージョンに含まれるコミットについては、こちらをご覧ください。

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 がリリースされました。このバージョンに含まれるコミットについては、こちらをご覧ください。

新機能

ベンチマークごとのサーマルスロットリングによるスリープ期間を完全な 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 がリリースされました。このバージョンに含まれるコミットについては、こちらをご覧ください。