捕获 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 - 从系统收到启动 intent 到渲染目标 activity 的第一帧的时间。
• timeToFullDisplayMs - 从系统收到启动 intent 到应用通过 reportFullyDrawn 方法报告已完成绘制的时间。当跟随在 reportFullyDrawn() 调用之后（或包含该调用）的第一帧完成渲染时，测量即会停止。Android 10（API 级别 29）及更低版本可能不支持此测量功能。

如需详细了解影响应用启动时间的各个因素，请查看应用启动时间页面。

FrameTimingMetric

FrameTimingMetric 会捕获基准测试所生成帧（如滚动或动画）的时间信息，并输出以下值：

• frameOverrunMs - 给定帧错过其截止时间多长时间。正数表示出现了丢帧和可见的卡顿，负数表示帧比其截止时间早多少时间结束。 仅适用于 Android 12（API 级别 31）及更高版本。
• frameDurationCpuMs - 在 CPU（界面线程和 RenderThread）上生成帧所花费的时间。

系统会按以下分布来收集这些测量值：第 50 个、第 90 个、第 95 个和第 99 个百分位。

如需详细了解如何发现和改进渲染速度缓慢的帧，请参见渲染速度缓慢。

TraceSectionMetric（实验性）

TraceSectionMetric 会捕获与提供的 sectionName 匹配的轨迹部分所花费的时间，并输出该时间的最小值、中位数和最大值（以毫秒为单位）。轨迹部分是通过 trace(sectionName){} 函数调用或者 Trace.beginSection(sectionName) 和 Trace.endSection()（或其异步变体）之间的代码来定义。该指标始终选择测量期间所捕获轨迹部分的第一个实例。

如需详细了解如何进行跟踪，请参见系统跟踪概览和定义自定义事件。

PowerMetric（实验性）

PowerMetric 会捕获所提供的 categories 在测试期间的耗电量或能量变化。每个选定类别可拆分为多个可衡量的子组件，而未选择的类别则添加到“未选择”指标中。请注意，指标测量的是系统级消耗，而不是每个应用的消耗，并且目前只适用于 Pixel 6 和 Pixel 6 Pro 设备。

• power<category>Uw - 此类别在测试期间的耗电量。
• energy<category>Uws - 此类别在测试期间每单位时间传输的能量。

类别包括：CPU、DISPLAY、GPU、GPS、MEMORY、MACHINE_LEARNING、NETWORK 和 UNCATEGORIZED。

对于某些类别（如 CPU），可能很难将其他进程执行的工作与您自己的应用执行的工作区分开来。请尝试移除或限制不必要的应用和帐号，最大限度地减少干扰。