擷取 Macrobenchmark 指標

概念和 Jetpack Compose 實作

指標是指透過效能評定擷取的主要類型資訊。系統會將這些值以 List 的形式傳送至 measureRepeated 函式，您就能一次指定多個評估指標。基準測試需要至少一種指標才能執行。

下列程式碼片段會擷取影格時間和自訂追蹤區塊的指標：

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 是 RecyclerView 中定義的可追蹤區塊 ID。createViewHolder() 方法的原始碼範例則說明如何在自己的程式碼中定義可追蹤區塊。

本文稍後會詳細說明 StartupTimingMetric、TraceSectionMetric 和 FrameTimingMetric。如需完整指標清單，請查看 Metric 的子類別。

基準測試結果會輸出到 Android Studio，如圖 1 所示。如果定義了多項指標，所有指標都會合併到輸出內容。

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 結果。