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

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

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

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

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

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

StartupTimingMetric、TraceSectionMetric、FrameTimingMetric、PowerMetric の詳細については、このドキュメントの後半で説明します。

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

StartupTimingMetric

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

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

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

起動時間の精度を改善する

アプリの起動時間を測定するための主な 2 つの指標は、初期表示までの時間（TTID）と完全表示までの時間（TTFD）です。TTID はアプリの UI の最初のフレームを表示するのにかかる時間です。TTFD には最初のフレームが表示された後に非同期で読み込まれるコンテンツを表示する時間も含まれます。

TTFD は ComponentActivity の reportFullyDrawn() メソッドが呼び出されると報告されます。reportFullyDrawn() が呼び出されない場合、代わりに TTID が報告されます。reportFullyDrawn() が呼び出されるタイミングを非同期読み込みが完了するまで遅らせることが必要になる場合があります。たとえば、UI に RecyclerView や遅延リストなどの動的リストが含まれている場合、リストが最初に描画された後、つまり UI が完全に描画されたとマークされた後で完了するバックグラウンド タスクによって、データが入力される場合があります。この場合、リストへのデータ入力はベンチマークに含まれません。

リストへのデータ入力をベンチマーク時間に含めるには、getFullyDrawnReporter() を使用して FullyDrawnReporter を取得し、アプリコードでレポーターを追加します。レポーターはバックグラウンド タスクでリストへのデータ入力が完了したら解放する必要があります。

追加されたすべてのレポーターが解放されるまで、FullyDrawnReporter は reportFullyDrawn() メソッドを呼び出しません。バックグラウンド プロセスが完了するまでレポーターを追加しておくことで、リストにデータを入力するのにかかる時間も起動時間データに含まれるようになります。これによって、ユーザーから見たアプリの動作が変わることはありませんが、リストにデータを入力するのにかかる時間が起動時間データに含まれるようになります。

アプリで Jetpack Compose を使用している場合は、以下の API を使用して完全に描画された状態を示せます。

• ReportDrawn: コンポーザブルですぐにインタラクションに対応できる準備が整っていることを示します。
• ReportDrawnWhen: コンポーザブルでインタラクションの準備が整ったタイミングを示す list.count > 0 などの述語を受け取ります。
• ReportDrawnAfter: 完了時にコンポーザブルでインタラクションの準備が整ったことを示す停止中のメソッドを受け取ります。

FrameTimingMetric

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

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

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

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

TraceSectionMetric

TraceSectionMetric は、指定された sectionName に一致するトレース セクションが発生した回数と所要時間をキャプチャします。時間については、最小値、中央値、最大値がミリ秒単位で出力されます。トレース セクションは、関数呼び出し trace(sectionName) か、Trace.beginSection(sectionName) と Trace.endSection()（またはこれらの非同期バリアント）の間のコードで定義されます。常に、測定中にキャプチャされたトレース セクションの最初のインスタンスが選択されます。デフォルトでは、パッケージからのトレース セクションのみを出力します。パッケージ外のプロセスを含めるには、targetPackageOnly = false を設定します。

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

PowerMetric

PowerMetric は、指定された電力カテゴリのテスト中における電力またはエネルギーの変化を取得します。選択された各カテゴリは測定可能なサブコンポーネントに分類され、選択されていないカテゴリは「未選択」の指標に追加されます。

これらの指標はアプリごとの消費量ではなく、システム全体の消費量を測定するものであり、Google Pixel 6 と Google Pixel 6 Pro 以降のデバイスに限定されます。

• power<category>Uw: このカテゴリでのテスト期間中における電力消費量。
• energy<category>Uws: このカテゴリでのテスト期間中における時間単位あたりのエネルギー伝送量。

カテゴリには次のものがあります。

• CPU
• DISPLAY
• GPU
• GPS
• MEMORY
• MACHINE_LEARNING
• NETWORK
• UNCATEGORIZED

CPU などの一部のカテゴリでは、他のプロセスによる作業と実際のアプリによる作業を切り分けることが難しい場合があります。干渉を最小限に抑えるために、不要なアプリやアカウントを削除するか制限してください。