Macrobenchmark の指標をキャプチャする

指標は、ベンチマークから抽出される主要な情報タイプです。指標は List として measureRepeated 関数に渡されます。つまり、一度に複数の測定指標を指定できます。ベンチマークを実行するには、少なくとも 1 つのタイプの指標が必要です。

次のスニペットは、フレーム時間指標とカスタム トレース セクション指標をキャプチャします。

Kotlin

benchmarkRule.measureRepeated(
    packageName = TARGET_PACKAGE,
    metrics = listOf(
        FrameTimingMetric(),
        TraceSectionMetric("RV CreateView"),
        TraceSectionMetric("RV OnBindView"),
    ),
    // ...
)

Java

benchmarkRule.measureRepeated(
    /* packageName */ TARGET_PACKAGE,
    /* metrics */ Arrays.asList(
        new StartupTimingMetric(),
        new TraceSectionMetric("RV CreateView"),
        new TraceSectionMetric("RV OnBindView"),
    ),
    /* iterations */ 5,
    // ...
);

ベンチマーク結果は、次の画像のように Android Studio に出力されます。複数の指標が定義されている場合は、出力の中ですべての指標が結合されます。

TraceSectionMetric と FrameTimingMetric の結果

StartupTimingMetric

StartupTimingMetric は、以下の値を使用してアプリの起動時間の指標をキャプチャします。

  • timeToInitialDisplayMs – システムが起動インテントを受け取ってから、デスティネーション アクティビティの最初のフレームをレンダリングするまでの時間。
  • timeToFullDisplayMs - システムが起動インテントを受け取ってから、アプリが reportFullyDrawn メソッドを使用して完全な描画を報告するまでの時間。測定は、reportFullyDrawn() の呼び出しを含む（または呼び出し後の）最初のフレームのレンダリングが完了した時点で停止します。この測定は、Android 10（API レベル 29）以前では利用できない場合があります。

アプリの起動時間に影響する要因について詳しくは、アプリの起動時間のページをご確認ください。

StartupTimingMetric の結果

FrameTimingMetric

FrameTimingMetric は、ベンチマークによって生成される、スクロールやアニメーションなどのフレームの時間情報をキャプチャして、以下の値を出力します。

  • frameOverrunMs – 特定のフレームが期限を超過した時間。正の数値はフレーム落ちや目に見えるジャンク / スタッターを示し、負の数値はフレームが期限よりどれだけ早く終了したかを示します。Android 12（API レベル 31）以上でのみ利用可能です。
  • frameDurationCpuMs – CPU 上の UI スレッドと RenderThread の両方でフレームが生成されるのにかかった時間。

これらの測定値は、50 パーセンタイル、90 パーセンタイル、95 パーセンタイル、99 パーセンタイルの分布で収集されます。

遅いフレームを特定して改善する方法については、遅いレンダリングをご覧ください。

FrameTimingMetric の結果

TraceSectionMetric（試験運用版）

TraceSectionMetric は、指定された sectionName と一致するトレース セクションにかかった時間をキャプチャし、最小値、中央値、最大値の時間をミリ秒単位で出力します。トレース セクションは、関数呼び出し trace(sectionName){} か、Trace.beginSection(sectionName) と Trace.endSection()（またはこれらの非同期バリアント）の間のコードで定義されます。測定中にキャプチャされたトレース セクションの最初のインスタンスが常に選択されます。

トレースについて詳しくは、システム トレースの概要とカスタム イベントを定義するをご覧ください。

TraceSectionMetric の結果