Benchmark

在 Android Studio 中准确衡量代码性能。
最近更新时间 当前稳定版 下一候选版 Beta 版 Alpha 版
2021 年 11 月 17 日 1.0.0 - - 1.1.0-alpha12

声明依赖项

如需添加 Benchmark 的依赖项,您必须将 Google Maven 代码库添加到项目中。有关详情,请阅读 Google 的 Maven 代码库

在应用或模块的 build.gradle 文件中添加所需工件的依赖项:

Groovy

dependencies {
    androidTestImplementation "androidx.benchmark:benchmark-junit4:1.0.0"
}

android {
    ...
    defaultConfig {
        ...
        testInstrumentationRunner "androidx.benchmark.junit4.AndroidBenchmarkRunner"
    }
}

Kotlin

dependencies {
    androidTestImplementation("androidx.benchmark:benchmark-junit4:1.0.0")
}

android {
    ...
    defaultConfig {
        ...
        testInstrumentationRunner = "androidx.benchmark.junit4.AndroidBenchmarkRunner"
    }
}

Benchmark 库还提供了可与基准模块搭配使用的 Gradle 插件。此插件可设置模块的默认 build 配置,设置将基准输出复制到主机,并提供 ./gradlew lockClocks 任务

如需使用该插件,请在顶级 build.gradle 文件中添加以下 classpath

Groovy

buildscript {
    repositories {
        google()
    }
    dependencies {
        classpath "androidx.benchmark:benchmark-gradle-plugin:1.0.0"
    }
}

Kotlin

buildscript {
    repositories {
        google()
    }
    dependencies {
        classpath("androidx.benchmark:benchmark-gradle-plugin:1.0.0")
    }
}

然后,将该插件应用到基准模块的 build.gradle 文件

Groovy

plugins {
  id 'androidx.benchmark'
}

Kotlin

plugins {
    id("androidx.benchmark")
}

Macrobenchmark

如需在项目中使用 Macrobenchmark,请将以下依赖项添加到应用或模块的 build.gradle 文件中:

Groovy

dependencies {
  androidTestImplementation "androidx.benchmark:benchmark-macro-junit4:1.1.0-alpha12"
}

Kotlin

dependencies {
  androidTestImplementation("androidx.benchmark:benchmark-macro-junit4:1.1.0-alpha12")
}

反馈

您的反馈将帮助我们改进 Jetpack。如果您发现了新问题,或对此库的改进有自己的见解,请告诉我们。创建新问题前,请先查看此库中的现有问题。您可以点击星标按钮,为现有问题投票。

创建新问题

如需了解详情,请参阅问题跟踪器文档

版本 1.1.0

版本 1.1.0-alpha12

2021 年 11 月 17 日

发布了 androidx.benchmark:benchmark-*:1.1.0-alpha12版本 1.1.0-alpha12 中包含这些提交内容

新功能

  • 针对基于轨迹的自定义时间测量增加了实验性 TraceSectionMetric。(I99db1b/204572664

bug 修复

  • 每次迭代时唤醒设备,以确保可以测试界面 - 需要停用锁屏功能。(Ibfa28b/180963442
  • 修复了模拟器和未取得 root 权限的设备在 StackSampling 分析模式下多次崩溃的问题(Icdbdab/202719335
  • 移除了每次迭代结束时 0.5 秒的休眠时间 - 如果您发现此次更改后缺少一些指标,请提交 bug。(Iff6aa)
  • 降低了数据丢失的几率,并减少了跟踪记录的内存开销(Id2544b/199324831b/204448861
  • 改为内存占用较小的 sched 存储格式,将轨迹大小缩减了约 40%。(Id5fb6b/199324831
  • 将启动指标的实现更新为始终在 renderthread 结束时结束。这将使各个平台版本间的测量结果更为一致,并且更贴近应用内衡量结果。(Ic6b55)

版本 1.1.0-alpha11

2021 年 11 月 3 日

发布了 androidx.benchmark:benchmark-*:1.1.0-alpha11版本 1.1.0-alpha11 中包含这些提交内容

API 变更

  • Macrobenchmark 现在的 minSdkVersion23。(If2655)
  • 新增了一个实验性 BaselineProfileRule,能够为应用的关键用户历程生成基准配置文件。后面提供了详细文档。(Ibbefab/203692160
  • 移除了为 Java 调用方添加的 measureRepeated 接口变体,因为它会导致在完成/解析该方法是产生歧义。Java 调用方将需要再从 measureRepeated 返回 Unit.Instance。如果由此给您带来不便,请提交 bug,我们会在未来版本中细探这一问题。(Ifb23eb/204331495

版本 1.1.0-alpha10

2021 年 10 月 27 日

发布了 androidx.benchmark:benchmark-*:1.1.0-alpha10版本 1.1.0-alpha10 中包含这些提交内容

API 变更

  • 向后移植 StartupTimingMetric 以向后兼容 API 23。这一新实现还能更好地处理 reportFullyDrawn(),以等待相应内容的呈现。(If3ac9b/183129298
  • 为 Java 调用方的多个 MacrobenchmarkScope 方法添加了 JvmOverloads。(I644feb/184546459
  • 提供了备用 MacrobenchmarkRule.measureRepeated 函数,该函数使用 Consumer<MacrobenchmarkScope> 实现 Java 语言中的惯用用法。(If74abb/184546459

bug 修复

  • 修复了跟踪记录未尽早开始以及缺少指标数据的问题。这应该可以修复由库本身引起的“在基准运行期间无法读取任何指标”异常。(I6dfcbb/193827052b/200302931
  • FrameNegativeSlack 已重命名为 FrameOverrun 以阐明其的含义:帧超出其时间预算的程度。(I6c2aab/203008701

版本 1.1.0-alpha09

2021 年 10 月 13 日

发布了 androidx.benchmark:benchmark-*:1.1.0-alpha09版本 1.1.0-alpha09 中包含这些提交内容

bug 修复

版本 1.1.0-alpha08

2021 年 9 月 29 日

发布了 androidx.benchmark:benchmark-*:1.1.0-alpha08版本 1.1.0-alpha08 中包含这些提交内容

API 变更

  • 使滚动 macrobenchmark 可以往回运行到 API 23(If39c2b/183129298
  • 向界面和 JSON 输出添加了新型采样指标,侧重于每次迭代多个样本的百分位数。(I56247b/199940612
  • 整个基准库都改为使用浮点指标(在 Studio 界面中会被截断)。(I69249b/197008210

版本 1.1.0-alpha07

2021 年 9 月 1 日

发布了 androidx.benchmark:benchmark-*:1.1.0-alpha07版本 1.1.0-alpha07 中包含这些提交内容

API 变更

  • 将最低的 API 级别提升到了 21,以反映未来预期支持的最低 API 级别。当前支持的最低 API 级别仍通过 requiredApi() 传达,目前为 29(I440d6b/183129298

bug 修复

  • 修复了 ProfileInstaller,以更方便使用基准配置文件的应用使用 CompilationMode.BaselineProfile 运行 MacroBenchmark。(I42657b/196074999)注意:还需要更新到 androidx.profileinstaller:profileinstaller:1.1.0-alpha04 或更高版本。
  • StartupMode.COLD + CompilationMode.None 基准现在更加稳定。(I770cdb/196074999

版本 1.1.0-alpha06

2021 年 8 月 18 日

发布了 androidx.benchmark:benchmark-*:1.1.0-alpha06版本 1.1.0-alpha06 中包含这些提交内容

API 变更

  • 添加了 androidx.benchmark.iterations 插桩参数,以允许在本地进行测试/性能分析时手动替换迭代计数。(6188beb/194137879

bug 修复

  • 已在 API 29 及更高级别上切换到 Simpleperf 并将其作为默认采样性能分析器。(Ic4b34b/158303822

已知问题

  • CompilationMode.BaselineProfile 仍在开发中。目前,请避免使用它来确定配置文件的优良度。

版本 1.1.0-alpha05

2021 年 8 月 4 日

发布了 androidx.benchmark:benchmark-*:1.1.0-alpha05版本 1.1.0-alpha05 中包含这些提交内容。

由于间歇性崩溃问题,1.1.0-alpha04 已取消,未发布。b/193827052

API 变更

  • startActivityAndWait 切换为通过 am start 调用启动事件,这会使每次测量迭代的时间缩短约 5 秒,但代价是不再支持 intent parcelable。(I5a6f5b/192009149

bug 修复

  • 降低了热限制检测的激进性,并在频繁检测到节流时重新计算基准。(I7327b)
  • 修复了 FrameTimingMetric,以支持 Android S Beta 版(Ib60ccb/193260119
  • 使用 EmptyActivity 使目标应用退出强行停止状态,以便更好地支持 CompilationMode.BaselineProfile。(Id7cacb/192084204
  • 将轨迹文件扩展名更改为 .perfetto-trace,以符合平台标准。(I4c236b/174663039
  • StartupTimingMetric 现在会输出“fullDrawnMs”指标,以测量直到应用完成渲染所用的时间。如需为您的应用定义此指标,请在初始内容准备就绪时(例如,从数据库或网络加载初始列表项时)调用 Activity.reportFullyDrawn。(无需对 ComponentActivity 进行 build 版本检查即可使用 reportFullyDrawn 方法。)请注意,您的测试必须运行足够长的时间才能捕获此指标(startActivityAndWait 不会等待 reportFullyDrawn)。(If1141b/179176560
  • 将界面元数据附加到轨迹的时间缩短了 50 多毫秒(Ic8390b/193923003
  • 停止跟踪后轮询频率显著提高,这可将示例启动基准运行时间缩短 30% 以上(Idfbc1b/193723768

版本 1.1.0-alpha03

2021 年 6 月 16 日

发布了 androidx.benchmark:benchmark-*:1.1.0-alpha03版本 1.1.0-alpha03 中包含这些提交内容

新功能

bug 修复

  • 用于抑制基准错误的 Gradle 示例代码已更新为使用一个非弃用的 API,其语法也支持 .gradle.kts 用户。

    例如:

    testInstrumentationRunnerArguments["androidx.benchmark.suppressErrors"] = "EMULATOR,LOW-BATTERY"
    

版本 1.1.0-alpha02

2021 年 5 月 18 日

Benchmark 版本 1.1.0-alpha02 为基准化分析引入了一个重要组件 - Macrobenchmark。除了提供用于衡量 CPU 循环的基准之外,Macrobenchmark 还可用于衡量整个应用的互动(如启动和滚动)和捕获跟踪记录。如需了解详情,请参阅库文档

发布了 androidx.benchmark:benchmark-*:1.1.0-alpha02版本 1.1.0-alpha02 中包含这些提交内容

新功能

添加了 Macrobenchmark 工件(androidx.benchmark:benchmark-macro-junit4androidx.benchmark:benchmark-macro

  • 从应用(在本地或 CI 中)中捕获启动、滚动/动画性能指标
  • 从 Android Studio 中捕获和检查跟踪记录

bug 修复

  • 解决了 Android 12 上输出目录的 shell 权限问题(注意 - 可能需要将 Android Gradle 插件更新到 7.0.0 Canary 版以及将 Android Studio 更新为 Arctic Fox (2020.3.1)),以继续在受影响的设备上捕获输出文件。(Icb039)
  • 在 BenchmarkPlugin 中支持配置缓存(6be1c1b/159804788
  • 简化了文件输出 - 默认情况下,在不需要 requestLegacyExternalStorage=true 的目录中启用(8b5a4db/172376362
  • 修复了以下问题:库输出关于在没有 JIT 线程的平台版本上找不到 JIT 线程的 logcat 警告。(I9cc63b/161847393
  • 修复了读取设备最大频率的问题。(I55c7a)

版本 1.1.0-alpha01

2020 年 6 月 10 日

发布了 androidx.benchmark:benchmark-common:1.1.0-alpha01androidx.benchmark:benchmark-gradle-plugin:1.1.0-alpha01androidx.benchmark:benchmark-junit4:1.1.0-alpha01版本 1.1.0-alpha01 中包含这些提交内容

1.1 的新功能

  • 分配指标 - 基准现在会在预热和计时后运行一个额外的阶段,以捕获分配计数。分配可能会导致旧版平台出现性能问题(O 中的 140ns 变为 M 中的 8ns - 在 Nexus5X 上测量,时钟处于锁定状态)。该指标显示以下位置:在 Android Studio 控制台输出以及
  • 性能剖析支持 - 您现在可以捕获基准运行的性能剖析数据,以检查代码运行缓慢的原因。Benchmark 支持捕获方法跟踪记录或 ART 中的方法采样。您可以使用 Android Studio 中的性能剖析器(依次选择“File > Open”)来检查这些文件。
  • Benchmark Gradle 插件现在提供默认设置,以便简化设置过程:
    • testBuildType 默认设置为发布,以避免使用内置代码覆盖率的依赖项。发布 buildType 也会配置为默认 buildType,以便让 Android Studio 能够在首次打开某个项目时自动选择正确的构建变体。(b/138808399)
    • signingConfig.debug 用作默认的签名配置 (b/153583269)

** 问题修复 **

  • 显著降低了预热过渡开销,其中每个基准的首次测量值都因人为原因而高于其他测量值。该问题在非常小的基准(1 毫秒或更短)中更加明显。(b/142058671)
  • 修复了从命令行运行时针对每个基准输出的 InstrumentationResultParser 错误。(I64988b/154248456

已知问题

  • 命令行、Benchmark 的 Gradle 调用不直接输出结果。若要解决该问题,您可以查看 Studio,也可以解析 JSON 输出文件以获取结果。
  • Benchmark 报告无法从已安装应用 ID 以“android”或“download”(不区分大小写)结尾的应用的设备中提取报告。遇到该问题的用户应将 Android Gradle 插件升级到 4.2-alpha01 或更高版本。

版本 1.0.0

Benchmark 版本 1.0.0

2019 年 11 月 20 日

发布了 androidx.benchmark:benchmark-common:1.0.0androidx.benchmark:benchmark-gradle-plugin:1.0.0androidx.benchmark:benchmark-junit4:1.0.0,这些版本与 1.0.0-rc01 相比没有变化。版本 1.0.0 中包含这些提交内容

1.0.0 的主要功能

使用 Benchmark 库,您可为应用代码编写性能基准测试并快速获得分析结果。

它可以防止出现构建和运行时配置问题并稳定设备性能,以确保衡量值的准确性和一致性。直接在 Android Studio 中在持续集成中运行基准化分析,以观察代码性能随时间的变化情况,并防止出现回归。

主要功能包括:

  • 时钟稳定
  • 自动设置线程优先级
  • 支持界面性能测试,例如在 RecyclerView 示例
  • JIT 感知预热和循环
  • 用于后期处理的 JSON 基准输出

版本 1.0.0-rc01

2019 年 10 月 23 日

发布了 androidx.benchmark:benchmark-common:1.0.0-rc01androidx.benchmark:benchmark-gradle-plugin:1.0.0-rc01androidx.benchmark:benchmark-junit4:1.0.0-rc01版本 1.0.0-rc01 中包含这些提交内容

新功能

  • 向基准添加了 systrace 跟踪记录

bug 修复

  • 修复了由于优先级设置导致 JIT 无法在预热前结束的指标不稳定问题 (b/140773023)
  • 统一了 Android Gradle 插件 3.5 和 3.6 的 JSON 输出目录

版本 1.0.0-beta01

2019 年 10 月 9 日

发布了 androidx.benchmark:benchmark-common:1.0.0-beta01androidx.benchmark:benchmark-gradle-plugin:1.0.0-beta01androidx.benchmark:benchmark-junit4:1.0.0-beta01版本 1.0.0-beta01 中包含这些提交内容

新功能

  • 在每次预热之前运行垃圾回收,以减少从一个基准泄漏到下一个基准的内存压力 (b/140895105)

bug 修复

  • 添加了 androidx.annotation:android-experimental-lint 依赖项,以便在未使用实验性 API 时,Java 代码将正确生成 lint 错误,类似于 Kotlin 实验性注释针对 Kotlin 调用方提供的内容。
  • 现在可正确检测 Android Gradle 插件 3.6 中输出的 additionalTestOutputDir 插桩参数的使用情况,了解 AGP 何时处理数据副本。
  • 修复了 JSON 中未检测到的时钟频率,以正确打印 -1 (b/141945670)。

版本 1.0.0-alpha06

2019 年 9 月 18 日

发布了 androidx.benchmark:benchmark-common:1.0.0-alpha06androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha06androidx.benchmark:benchmark-junit4:1.0.0-alpha06版本 1.0.0-alpha06 中包含这些提交内容

新功能

  • 添加了检查以确定错误使用旧软件包的测试运行程序,该程序现在提供更有用的错误消息

API 变更

  • 实验性注解 ExperimentalAnnotationReport 现已正确公开。现在,使用实验性 BenchmarkState#report API 时需要此注释

版本 1.0.0-alpha05

2019 年 9 月 5 日

发布了 androidx.benchmark:benchmark-common:1.0.0-alpha05androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha05androidx.benchmark:benchmark-junit4:1.0.0-alpha05。点击此处可查看此版本中包含的提交内容。

API 变更

  • BenchmarkState.reportData API 现标记为实验性

bug 修复

  • 修复了时钟锁定脚本,该脚本在缺少 cutexpr shell 实用程序的设备上将失败。
  • 修复了 ./gradlew lockClocks 任务的问题,在以 su 实用程序的较旧版本(不支持 -c 标记)启用 root 权限的设备上该任务会暂挂。

版本 1.0.0-alpha04

2019 年 8 月 7 日

发布了 androidx.benchmark:benchmark-common:1.0.0-alpha04androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha04androidx.benchmark:benchmark-junit4:1.0.0-alpha04。点击此处可查看此版本中包含的提交内容。

此外还添加了有关如何在不使用 Gradle 的情况下使用 Benchmark 库的新文档,两者可用于不同的构建系统(例如 Bazel 或 Buck),以及在 CI 中运行时。如需了解详情,请参阅在不使用 Gradle 的情况下构建基准在持续集成中运行基准

新功能

  • Gradle 插件
    • 现在自动停用测试覆盖范围,并默认设置 AndroidBenchmarkRunner (b/138374050)
    • 增加了在运行基准和使用 AGP 3.6+ 时,对基于 AGP 的新数据副本的支持
  • 添加了 JSON 格式
    • 输出总基准测试运行时间 (b/133147694)
    • 现在,使用名称字符串(例如 @Parameters(name = "size={0},depth={1}"))的 @Parameterized 基准以 JSON 输出格式输出每个基准的参数名称和值 (b/132578772)
  • 模拟运行模式 (b/138785848)
    • 添加了“模拟运行”模式,仅运行每个基准循环一次以检查是否有错误/崩溃,而不捕获测量值。该模式非常有用,例如可在预提交中快速运行基准,以确认它们未损坏。

API 变更

  • 更改了模块结构,拆分了库 (b/138451391)
    • benchmark:benchmark-junit4 包含具有 JUnit 依赖项的类:AndroidBenchmarkRunnerBenchmarkRule。这两个类均已移入 androidx.benchmark.junit4 软件包中
    • benchmark:benchmark-common 包含其余逻辑,其中包括 BenchmarkState API
    • 通过这种拆分,该库将来可以在没有 JUnit4 API 的情况下支持基准化分析
  • 配置警告现在被视为错误,并且会使测试崩溃 (b/137653596)
    • 这样做是为了进一步鼓励准确测量,尤其是在 CI 中
    • 可以使用插桩参数将这些错误回退为警告。例如:-e androidx.benchmark.suppressErrors "DEBUGGABLE,LOW_BATTERY"

bug 修复

  • 写入 Q 设备上的外部存储空间时出现的错误会提供更具描述性的消息,并提供有关如何解决相应问题的建议
  • 在基准运行期间,屏幕会自动打开,而不是在屏幕关闭时失败

外部贡献

  • 感谢 Sergey Zakharov 为 JSON 输出改进以及修复屏幕关闭问题做出的贡献!

版本 1.0.0-alpha03

2019 年 7 月 2 日

发布了 androidx.benchmark:benchmark:1.0.0-alpha03androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha03。点击此处可查看此版本中包含的提交内容。

新功能

  • 在完整的 JSON 报告中公开每个基准因热节流而导致的休眠持续时间

bug 修复

  • 在 Android 插件和 Android 块之后,不再需要应用 Gradle 插件
  • 在使用分区存储的 Android 10 设备上添加了对基准报告的支持

版本 1.0.0-alpha02

2019 年 6 月 6 日

发布了 androidx.benchmark:1.0.0-alpha02androidx.benchmark:benchmark-gradle-plugin:1.0.0-alpha02。点击此处可查看此版本中包含的提交内容。

请注意,我们将 JSON 架构视为 API。我们计划遵循与其他 API 相同的稳定性约束:进入 Beta 版后架构即告稳定(极偶尔会有例外情况),最终版本中会修复所有相关问题,次要版本中只会添加新特性,而只会在主要版本中更改/移除特性。

API 变更

  • 翻新了 JSON 架构。对 JSON 架构的后续更改很可能仅限于新增特性:

    • 重新组织了结果对象结构,以支持将来的更多指标组 (b/132713021)
    • 在顶级对象中添加了测试运行上下文信息(例如,设备和 build 信息以及时钟是否处于锁定状态)(b/132711920)
    • 现在,时间指标名称中带有“ns”(b/132714527)
    • 扩充了每个报告指标的统计信息(最大值、中位数、最小值),并移除了简化的“nanos”摘要统计信息 (b/132713851)
  • 移除了 XML 输出 (b/132714414)

  • BenchmarkState.reportData API 中移除了热限制检测 (b/132887006)

bug 修复

  • 修复了 ./gradlew lockClocks 在某些最新的操作系统设备上不粘滞的问题 (b/133424037)
  • 停用了模拟器的限制检测 (b/132880807)

版本 1.0.0-alpha01

2019 年 5 月 7 日

发布了 androidx.benchmark:benchmark:1.0.0-alpha01。点击此处可查看此版本中包含的提交内容。