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

コンセプトと Jetpack Compose の実装

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

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

Kotlin

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

Java

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

この例では、RV CreateView と RV OnBindView が 追跡可能なブロックの ID で、RecyclerView で定義されます。The ソースコード forcreateViewHolder()the メソッドは、独自のコード内で追跡可能なブロックを定義する方法の例です。

StartupTimingMetric、TraceSectionMetric、 FrameTimingMetric については、このドキュメントで後ほど詳しく説明します。指標の完全なリストについては、Metric のサブクラスをご覧ください。

図 1 のとおり、ベンチマーク結果は Android Studio に出力されます。複数の指標が定義されている場合は、出力の中ですべての指標が結合されます。

TraceSectionMetric と FrameTimingMetric の結果
図 1. TraceSectionMetric と FrameTimingMetric の結果

StartupTimingMetric

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

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

StartupTimingMetric は起動の反復処理の最小値、中央値、最大値を出力します。起動の改善を評価する際には、常に中央値を重視します。中央値は一般的なユーザーの起動時間を最も適切に推測できます。アプリの起動時間に影響する要因について詳しくは、アプリの起動時間をご確認ください。

StartupTimingMetric の結果
図 2. StartupTimingMetric の結果

FrameTimingMetric

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

  • frameOverrunMs: 指定されたフレームが期限を超過した時間。 正の数値は、目に見えるジャンクまたはスタッターを伴うフレーム落ちを示します。負の数値は、フレームがサブシステムのハードウェアの期限よりどれだけ早く完了したかを示します。注: この指標は Android 12（API レベル 31）以降でのみ利用可能です。
  • frameDurationCpuMs: UI スレッドと RenderThread の両方でフレームの生成に CPU でかかった時間。

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

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

FrameTimingMetric の結果
図 3. FrameTimingMetric の結果

TraceSectionMetric

TraceSectionMetric は、特定のトレース セクションが発生した回数と、実行にかかる絶対時間をキャプチャします。時間トラッキングについては、最小値、中央値、最大値がミリ秒単位で出力されます。

ターゲット トレース セクションは、関数呼び出し trace(sectionName) か、 Trace.beginSection(sectionName) と Trace.endSection() の間の下位レベルのブロック境界（またはこれらの 非同期バリアント）で定義されます。常に、測定中にキャプチャされたトレース セクションの最初のインスタンスが選択されます。デフォルトでは、パッケージからのトレース セクションのみを出力します。パッケージ外のプロセスを含めるには、targetPackageOnly = falseを設定します。

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

TraceSectionMetric
図 4. TraceSectionMetric の結果