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

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

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

@OptIn(ExperimentalMetricApi::class)
    @Test
    fun scrollComposeList() {
        benchmarkRule.measureRepeated(
            // [START_EXCLUDE]
            packageName = TARGET_PACKAGE,
            metrics = listOf(
                FrameTimingMetric(),
                // Measure power usage. This is supported on Pixel 6 and later.
                PowerMetric(PowerMetric.Type.Power(
                    mapOf(
                        PowerCategory.CPU to PowerCategoryDisplayLevel.TOTAL,
                        PowerCategory.DISPLAY to PowerCategoryDisplayLevel.TOTAL,
                        PowerCategory.GPU to PowerCategoryDisplayLevel.TOTAL,
                        PowerCategory.NETWORK to PowerCategoryDisplayLevel.TOTAL,
                    )
                )),
                // Measure custom trace sections by name EntryRow (which is added to the EntryRow composable).
                // Mode.Sum measures combined duration and also how many times it occurred in the trace.
                // This way, you can estimate whether a composable recomposes more than it should.
                TraceSectionMetric("EntryRowCustomTrace", TraceSectionMetric.Mode.Sum),
                // This trace section takes into account the SQL wildcard character %,
                // which can find trace sections without the full name.
                // This way, you can measure composables produced by the composition tracing
                // and measure how long they took and how many times they recomposed.
                // WARNING: This metric only shows results when running with composition tracing, otherwise it won't be visible in the outputs.
                TraceSectionMetric("%EntryRow%", TraceSectionMetric.Mode.Sum),
            ),
            // Try switching to different compilation modes to see the effect
            // it has on frame timing metrics.
            compilationMode = CompilationMode.None(),
            startupMode = StartupMode.WARM, // restarts activity each iteration
            iterations = DEFAULT_ITERATIONS,
            // [END_EXCLUDE]
            setupBlock = {
                uiAutomator {
                    // Before starting to measure, navigate to the UI to be measured.
                    startIntent(Intent("$packageName.COMPOSE_ACTIVITY"))
                }
            }
        ) {
            uiAutomator {
                onElement { isScrollable }.fling(Direction.DOWN)
            }
        }
    }

次の例では、EntryRowCustomTrace は、標準の Kotlin trace(sectionName) { ... } ブロック ラッパーを使用してコンポーザブル アイテム レイヤ内で定義されたカスタム トレース セクションを表しています。TraceSectionMetric のデータを提供するには、アプリケーションの本番環境のコードベース内のターゲット UI コンポーネントを標準の Jetpack ランタイム trace ブロック ラッパーでラップする必要があります。

@Composable
private fun EntryRow(entry: Entry, modifier: Modifier = Modifier) = trace("EntryRowCustomTrace") {
    Card(modifier = modifier) {
        Row(verticalAlignment = Alignment.CenterVertically) {
            Text(
                text = entry.contents,
                modifier = Modifier
                    .padding(16.dp)
                    .wrapContentSize()
            )

            Spacer(modifier = Modifier.weight(1f))

            Checkbox(
                checked = false,
                onCheckedChange = {},
                modifier = Modifier.padding(16.dp)
            )
        }
    }
}

図 1 に示すように、ベンチマーク結果は Android Studio 内の [Benchmark] ターミナルタブに直接出力されます。複数の指標が定義されている場合は、計算されたすべてのデータポイントが概要ウィンドウに結合されます。

TraceSectionMetric と FrameTimingMetric の結果
図 1. 最新の Compose レイアウトの TraceSectionMetric と FrameTimingMetric のコンソール結果を組み合わせたもの。

StartupTimingMetric、FrameTimingMetric、TraceSectionMetric、PowerMetric については、以下で詳しく説明します。使用可能なベンチマーク指標の一覧については、API リファレンスの Metric のサブクラスをご覧ください。

StartupTimingMetric

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

  • timeToInitialDisplayMs: システムが起動インテントを受け取ってから、デスティネーション画面の最初のフレームをレンダリングするまでの時間。
  • timeToFullDisplayMs: システムが起動インテントを受け取ってから、アプリが内部プラットフォーム レポート メカニズムを使用して完全な描画を報告するまでの時間。測定は、完全に描画されたシグナル後またはシグナルを含む最初のフレームのレンダリングが完了した時点で停止します。

StartupTimingMetric は起動の反復処理の最小値、中央値、最大値を出力します。起動の改善を評価する際には、常に中央値を重視します。中央値は一般的なユーザーの起動時間を最も適切に推測できます。

Compose ファーストのアーキテクチャでは、activity.reportFullyDrawn を手動で呼び出さないでください。代わりに、画面コンポーザブル内で Compose セーフな非同期ユーティリティ ReportDrawn、ReportDrawnWhen、または ReportDrawnAfter を使用して、非同期ネットワーク データまたは複雑な UI 状態のレンダリングが完了したときに Macrobenchmark に自動的に通知します。

初期化のパフォーマンスの分析と最適化について詳しくは、アプリの起動時間をご覧ください。

FrameTimingMetric

FrameTimingMetric は、リストのスクロールや複雑な UI レイアウトのアニメーションなど、ベンチマーク ジャーニーによって生成されるフレームから正確なタイミング情報をキャプチャし、次の診断値を出力します。

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

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

frameDurationCpuMs P50 3.5, P90 6.0, P95 6.4, P99 11.0
frameOverrunMs P50 -11.6, P90 -7.2, P95 -7.1, P99 -1.2

Jetpack Compose レイアウト階層を最適化する際は、パフォーマンスが最も低いフレーム（P95 と P99 の境界）を確認します。frameOverrunMs が高いパーセンタイルで正の整数に急上昇している場合は、スクロール アニメーションの負荷が高いときに再コンポーズによってメインスレッドが停止していることを示します。

遅いフレームを特定して解決するための詳細な分析情報については、Jetpack Compose のパフォーマンスをご覧ください。

TraceSectionMetric

TraceSectionMetric は、特定のトレース セクションが発生した回数と、実行にかかった絶対時間をキャプチャします。時間トラッキングについては、最小値、中央値、最大値がミリ秒単位で出力されます。ターゲット トレース セクションは、関数呼び出し trace(sectionName) か、Trace.beginSection(sectionName) と Trace.endSection() の間の下位レベルのブロック境界（またはこれらの非同期バリアント）で定義されます。

EntryRowCustomTraceCount min 20.0, median 28.0, max 50.0
EntryRowCustomTraceSumMs min 34.9, median 44.4, max 66.6

デフォルトでは、この指標は独自のアプリケーション パッケージ バイナリから直接コンパイルされたトレース セクションのみを出力します。アプリのパッケージ境界外から発生したプロセスを含めるには、プロパティ targetPackageOnly = false を設定します。

Jetpack Compose ランタイム トレースを使用している場合、コンポジション トレースを有効にすると、手動でトレース ラッパーを記述しなくても、システム トレース グラフに個々のコンポーズ可能な関数を表示できます。

ターゲット アプリケーションに androidx.compose.runtime:runtime-tracing 依存関係を追加するだけで、手動プロファイラ トレースは十分ですが、Macrobenchmark 実行内でこれらのトレースをプログラムでキャプチャするには、ベンチマーク モジュール内に追加の構成が必要です。

セットアップ手順の詳細は、Jetpack Macrobenchmark を使用してトレースをキャプチャするをご覧ください。

PowerMetric

PowerMetric は、Macrobenchmark の実行期間中の電力またはエネルギーの変化を取得します。選択された各カテゴリは測定可能なハードウェア コンポーネントに分類され、選択されていないカテゴリは「未選択」バケットにグループ化されます。

ハードウェア要件: これらの指標は、アプリごとの計算ではなく、システム全体の消費量を測定します。そのため、データの収集は Google Pixel 6、Google Pixel 6 Pro、およびそれ以降の実機に限定されます。

この指標は、カテゴリごとに 2 つの測定値を出力します。

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

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

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

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

powerCategoryCpuUw min 300.2, median 346.1, max 519.6
powerCategoryDisplayUw min 319.8, median 325.8, max 329.7
powerCategoryGpuUw min 18.8, median 23.3, max 36.9
powerCategoryNetworkUw min 97.3, median 123.3, max 681.3
powerTotalUw min 1234.8, median 1316.6, max 2112.4
powerUnselectedUw       min  483.3,  median  512.6,  max  561.7

コア サブシステムの分析

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

ターミナルには、リクエストした構成がマッピングされます。

  • powerCategoryCpuUw: テスト期間中の CPU の電力消費量。
  • powerCategoryGpuUw: テスト期間中の GPU の電力消費量。
  • powerUnselectedUw: 初期化マップで明示的にリクエストされなかった、利用可能なすべてのハードウェア カテゴリの合計電力消費量。

実行中にハードウェア レールでデータが急増するのを防ぐため、Macrobenchmark ループを開始する前に、画面の明るさを固定値にロックし、デバイスの温度を安定させ、競合するバックグラウンド プロセスを閉じます。

参考情報

コンテンツの閲覧

前へ
ベンチマークを作成する
次へ
アプリを制御する