Microbenchmark インストルメンテーション引数

bookmark_border コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

次の計測引数を指定して、Microbenchmark の動作を設定します。これらは Gradle の設定に追加することも、コマンドラインから計測を実行する際に直接適用することもできます。Android Studio とコマンドラインのすべてのテスト実行にこれらの引数を設定するには、testInstrumentationRunnerArguments に追加します。

android {
    defaultConfig {
        // ...
        testInstrumentationRunnerArguments["androidx.benchmark.dryRunMode.enable"] = "true"
    }
}

Android Studio からベンチマークを実行するときに計測引数をセットアップすることもできます。引数を変更する手順は次のとおりです。

コマンドラインからベンチマークを実行する場合は、-P android.testInstrumentationRunnerArguments.[name of the argument] を使用します。

./gradlew :benchmark:connectedAndroidTest -P android.testInstrumentationRunnerArguments.androidx.benchmark.profiling.mode=StackSampling

am インストルメンテーション コマンドを直接呼び出す場合は（CI テスト環境で発生する可能性があります）、-e を使用して引数を am instrument に渡します。

adb shell am instrument -e androidx.benchmark.profiling.mode StackSampling -w com.example.macrobenchmark/androidx.benchmark.junit4.AndroidBenchmarkRunner

CI でベンチマークを構成する方法については、CI でベンチマークを実行するをご覧ください。

additionalTestOutputDir

JSON ベンチマーク レポートとプロファイリング結果を保存するデバイス上の場所を指定します。

• 引数タイプ: ファイルパスの文字列
• デフォルト設定: テスト APK の外部ディレクトリ

androidx.benchmark.cpuEventCounter.enable（試験運用版）

androidx.benchmark.cupEventCounter.events で指定された CPU イベントをカウントします。ルートアクセス権限が必要です。

• 引数タイプ: ブール値
• デフォルト: false

androidx.benchmark.cpuEventCounter.events（試験運用版）

カウントする CPU イベントの種類を指定します。この引数を使用するには、androidx.benchmark.cpuEventCounter.enable を true に設定する必要があります。

• 引数のタイプ: カンマ区切りの文字列のリスト
• 利用可能なオプション:
  • Instructions
  • CPUCycles
  • L1DReferences
  • L1DMisses
  • BranchInstructions
  • BranchMisses
  • L1IReferences
  • L1IMisses
• デフォルト: Instructions、CpuCycles、BranchMisses

androidx.benchmark.dryRunMode.enable

ベンチマークを 1 回のループで実行して、正常に機能するかどうかを検証できます。

これは次のことを意味します。

• 構成エラーは適用されません（エミュレータで定期的な正確性テストを実行しやすくするためなど）。
• ベンチマークはウォームアップなしで 1 つのループのみを実行します。
• ランタイムを短縮するために、測定値とトレースがキャプチャされない

これにより、ビルドと測定の正確性よりも、テスト スループットとベンチマーク ロジックの検証を重視して最適化されます。

• 引数タイプ: ブール値
• デフォルト設定: false

androidx.benchmark.iterations

時間ベースの目標イテレーション数をオーバーライドして、処理量に一貫性を持たせます。これは通常、プロファイリングを有効にして、異なる実装または実行を比較する際に、プロファイリング トレース内で一定量の作業が実行されるように設定したい場合にのみ有用です。それ以外のシナリオでは、測定の精度や安定性が低下する可能性があります。

• 引数のタイプ: 整数
• デフォルト設定: 指定なし

androidx.benchmark.junit4.SideEffectRunListener

ベンチマークの実行中に無関係なバックグラウンド処理が実行されると、一貫性のあるベンチマーク結果が得られない可能性があります。

ベンチマーク実行中のバックグラウンド処理を無効にするには、listener インストルメンテーション引数のタイプを androidx.benchmark.junit4.SideEffectRunListener に設定します。

• 引数タイプ: 文字列
• 利用可能なオプション:
  • androidx.benchmark.junit4.SideEffectRunListener
• デフォルト設定: 指定なし

androidx.benchmark.output.enable

結果の JSON ファイルを外部ストレージに書き込めるようにします。

• 引数タイプ: ブール値
• デフォルト設定: true

androidx.benchmark.profiling.mode

ベンチマークの実行中にトレース ファイルをキャプチャできるようにします。利用可能なオプションについては、Microbenchmark をプロファイリングするをご覧ください。

一部の Android OS バージョンでは、後続の測定に影響を与えることなくメソッド トレースをサポートしていません。マイクロベンチマークはこれを防ぐために例外をスローするため、安全な場合にのみ、デフォルト引数を使用してメソッド トレースをキャプチャしてください。問題 #316174880 をご覧ください。

• 引数のタイプ: 文字列
• 利用可能なオプション:
  • MethodTracing
  • StackSampling
  • None
• デフォルト: MethodTracing の安全なバージョン。デバイスが測定に影響を与えずにメソッド トレースをキャプチャできる場合にのみ、メソッド トレースをキャプチャします。

androidx.benchmark.suppressErrors

エラーのカンマ区切りのリストを受け入れて、警告に変換できます。

• 引数のタイプ: 文字列のリスト
• 利用可能なオプション:
  • DEBUGGABLE
  • LOW-BATTERY
  • EMULATOR
  • CODE-COVERAGE
  • UNLOCKED
  • SIMPLEPERF
  • ACTIVITY-MISSING
• デフォルト設定: 空のリスト