擷取 Macrobenchmark 指標

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

下列程式碼片段會擷取畫面時間和自訂追蹤記錄區段的指標。

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

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

效能評定結果會輸出到 Android Studio，如下圖所示。 如果您定義了多個指標，則所有指標都會合併到輸出內容。

StartupTimingMetric

StartupTimingMetric 會使用下列值擷取應用程式啟動時間指標：

• timeToInitialDisplayMs - 從系統接收啟動意圖到顯示活動第一個畫面的時間。
• timeToFullDisplayMs - 系統接收啟動意圖到應用程式報告完整呈現的時間 (透過 reportFullyDrawn 方法完成)。發出 (或包含) reportFullyDrawn() 呼叫後，在第一個畫面算繪完成時，測量便會停止。上述測量方式可能不適用於 Android 10 (API 層級 29) 以下層級。

如要進一步瞭解影響應用程式啟動時間的因素，請參閱應用程式啟動時間頁面。

FrameTimingMetric

FrameTimingMetric 會從效能評定產生的畫面擷取時間資訊 (例如：捲動或動畫)，然後輸出下列值：

• frameOverrunMs - 顯示特定畫面過期多久。 正數代表捨棄的畫面，以及可見的資源浪費/延遲，負數則代表畫面快於期限的時間。僅適用於 Android 12 (API 層級 31) 以上版本。
• frameDurationCpuMs：畫面在 CPU 上 的 UI 執行緒和 RenderThread 產生的時間。

測量結果的分布依序為百分之 50、90、95 和 99。

如要進一步瞭解如何找出及改善緩慢畫面，請參閱「轉譯速度緩慢」。

TraceSectionMetric (實驗版)

TraceSectionMetric 會擷取與特定 sectionName 相符的追蹤區段耗費時間，並以毫秒為單位輸出最短、中位和最長時間。追蹤區段是由函式呼叫 trace(sectionName){}，或由 Trace.beginSection(sectionName) 和 Trace.endSection() 之間的程式碼 (或兩者的非同步變化版本) 定義。系統一律會選取測量期間擷取的第一個追蹤區段。

如要進一步瞭解追蹤功能，請參閱系統追蹤總覽和定義自訂事件。

PowerMetric (實驗版)

針對您提供的 categories，PowerMetric 會擷取測試期間的電量或能量變化。每個所選類別都會細分為可測量的子元件，而未選取的類別則會計入「未選取」指標。請注意，指標是用來測量整個系統 (而非個別應用程式) 的耗電量，且目前只適用於 Pixel 6 和 Pixel 6 Pro 裝置。

• power<category>Uw：這個類別在測試期間的耗電量。
• energy<category>Uws：這個類別在測試期間每單位時間所轉移的能量。

類別包括：CPU、DISPLAY、GPU、GPS、MEMORY、MACHINE_LEARNING、NETWORK 和 UNCATEGORIZED。

在 CPU 等某些類別中，可能很難區分完成工作的是其他程序或您的應用程式。請嘗試移除或限制不必要的應用程式和帳戶，將干擾降到最低。