捕获 Macrobenchmark 指标

概念和 Jetpack Compose 实现

指标是指从基准测试中提取的主要信息类型。这些指标会以 List 的形式传递给 measureRepeated 函数；也就是说，您可以一次性指定多个测量指标。若要运行基准测试，必须至少提供 1 种类型的指标。

以下代码段会捕获帧时间和自定义的轨迹部分指标：

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 是 可跟踪代码块的 ID，这些代码块定义在 RecyclerView 中。The source code for the createViewHolder() 方法的源代码示例展示了如何在您自己的代码中定义 可跟踪代码块。

本文档稍后将详细介绍 StartupTimingMetric、TraceSectionMetric 和 FrameTimingMetric。如需查看指标的完整列表，请查看 Metric 的子类。

基准测试结果会输出到 Android Studio，如图 1 所示。如果定义了多个指标，则所有这些指标会在输出中合并到一处。

TraceSectionMetric 和 FrameTimingMetric 的结果。
图 1. TraceSectionMetric 和 FrameTimingMetric 的结果。

StartupTimingMetric

StartupTimingMetric 可捕获提供以下值的应用启动时间指标：

  • timeToInitialDisplayMs：从系统收到 启动 intent 到渲染目标 Activity的第一帧所用的时间。
  • timeToFullDisplayMs：从系统收到 启动 intent 到应用使用 reportFullyDrawn()方法报告已完全绘制所用的时间。测量会在渲染完 reportFullyDrawn() 调用之后（或包含该调用）的第一帧时停止。Android 10（API 级别 29）及更低版本可能不支持此测量功能。

StartupTimingMetric 会输出启动迭代的最小值、中位数值和最大值。如需评估启动方面的改进，请始终重点关注中位数值，因为它们能够最准确地估算典型用户启动时间。如需详细了解影响应用启动时间的各个因素，请参阅应用启动 时间。

StartupTimingMetric 结果
图 2. StartupTimingMetric 结果。

FrameTimingMetric

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

  • frameOverrunMs：给定帧完全呈现用时与其呈现时限相差的时长。 正数表示出现了丢帧和可见的卡顿。负数表示帧完全呈现用时比子系统硬件呈现时限少多少时间。注意：此指标仅适用于 Android 12（API 级别 31）及更高版本。
  • frameDurationCpuMs：通过界面线程和 RenderThread 在 CPU 中生成帧所用的时间。

系统会收集分布在第 50 个、第 90 个、第 95 个和第 99 个百分位的以上测量值。

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

FrameTimingMetric 结果
图 3. FrameTimingMetric 结果。

TraceSectionMetric

TraceSectionMetric 会捕获特定轨迹部分发生的次数以及执行该轨迹部分所用的绝对时间。对于时间跟踪，它会输出以毫秒为单位的最小时间、中位时间和最大时间。

目标轨迹部分是通过函数调用 trace(sectionName)或者 Trace.beginSection(sectionName)和Trace.endSection()之间的较低级别块边界（或其 异步变体）来定义。该指标始终选择测量期间所捕获的第一个轨迹部分实例。默认情况下，它仅输出您的软件包中的轨迹部分；如需加入软件包以外的进程，请设置 targetPackageOnly = false。

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

TraceSectionMetric
图 4. TraceSectionMetric 结果。