捕获 Macrobenchmark 指标

指标是从基准中提取的主要信息类型。它们作为 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 和 PowerMetric，将在本文档后面详细介绍。

基准测试结果将输出到 Android Studio，如图 1 所示。如果定义了多个指标，则所有指标都将组合在输出中。

Results of TraceSectionMetric and FrameTimingMetric. — **图 1.** `TraceSectionMetric` 和 `FrameTimingMetric` 的结果。

StartupTimingMetric

StartupTimingMetric 捕获应用启动计时指标，包含以下值

timeToInitialDisplayMs：从系统接收启动意图到渲染目标 Activity 的第一帧所用的时间。
timeToFullDisplayMs：从系统接收启动意图到应用使用 reportFullyDrawn() 方法报告完全绘制所用的时间。测量在渲染 reportFullyDrawn() 调用之后或包含该调用的第一帧完成后停止。此测量结果可能在 Android 10 (API 级别 29) 及更早版本上不可用。

StartupTimingMetric 输出启动迭代的最小值、中位数和最大值。为了评估启动改进，您应该关注中位数，因为它们提供了典型启动时间的最佳估计。有关导致应用启动时间的更多信息，请参阅应用启动时间。

StartupTimingMetric results — **图 2.** `StartupTimingMetric` 结果。

FrameTimingMetric

FrameTimingMetric 捕获由基准（例如滚动或动画）生成的帧的计时信息，并输出以下值

frameOverrunMs：给定帧超出其截止时间的时间量。正数表示丢帧以及可见的卡顿或停顿。负数表示帧比截止时间快多少。注意：这仅在 Android 12 (API 级别 31) 及更高版本上可用。
frameDurationCpuMs：帧在 CPU 上（包括 UI 线程和 RenderThread）生成所需的时间。

这些测量结果按第 50、90、95 和 99 百分位数进行分布收集。

有关如何识别和改进慢帧的更多信息，请参阅渲染缓慢。

FrameTimingMetric results — **图 3.** `FrameTimingMetric` 结果。

TraceSectionMetric

TraceSectionMetric 捕获与所提供 sectionName 匹配的跟踪部分发生的次数及其所需时间。对于时间，它输出以毫秒为单位的最小值、中位数和最大值。跟踪部分由函数调用 trace(sectionName) 或 Trace.beginSection(sectionName) 和 Trace.endSection() 之间的代码或其异步变体定义。它总是选择在测量期间捕获的跟踪部分的第一个实例。默认情况下，它只输出您包中的跟踪部分；要包含您包之外的进程，请设置 targetPackageOnly = false。

有关跟踪的更多信息，请参阅系统跟踪概览和定义自定义事件。