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

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

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

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

  1. [Edit] をクリックしてから、編集する設定を選択して、実行設定を編集します。
    図 1.実行設定を編集する
  2. [Instrumentation arguments] フィールドの横にある をクリックして、インストルメンテーション引数を編集します。
    図 2.インストルメンテーション引数の編集
  3. をクリックし、必要なインストルメンテーション引数を追加します。
    図 3.インストルメンテーション引数の追加

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

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

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

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

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

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.killExistingPerfettoRecordings

Benchmark は、干渉を減らすため、新しいトレースを開始するときに既存の Perfetto（システム トレース）の記録をデフォルトで終了します。この動作を無効にするには、false を渡します。

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

androidx.benchmark.output.enable

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

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

androidx.benchmark.profiling.mode

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

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

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

androidx.benchmark.suppressErrors

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

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

additionalTestOutputDir

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

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

listener

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

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

  • 引数タイプ: 文字列
  • 利用可能なオプション:
    • androidx.benchmark.junit4.SideEffectRunListener
  • デフォルト設定: 指定なし
前へ
ベンチマークをプロファイリングする
次へ
Microbenchmark と Hilt