Microbenchmark 插桩参数

bookmark_border 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

您可以使用以下插桩参数配置 Microbenchmark 的行为。这些参数既可以添加到 Gradle 配置中，也可以在从命令行运行插桩时直接应用。如需针对所有 Android Studio 和命令行测试运行来设置这些参数，请将所需参数添加到 testInstrumentationRunnerArguments 中：

android {
    defaultConfig {
        // ...
        testInstrumentationRunnerArguments["androidx.benchmark.dryRunMode.enable"] = "true"
    }
}

您还可以在从 Android Studio 运行基准测试时设置插桩参数。如需更改参数，请执行以下操作：

如果您要从命令行运行基准测试，请使用 -P android.testInstrumentationRunnerArguments.[name of the argument]：

./gradlew :benchmark:connectedAndroidTest -P android.testInstrumentationRunnerArguments.androidx.benchmark.profiling.mode=StackSampling

如果您直接调用 am 插桩命令（在 CI 测试环境中可能就是这种情况），请使用 -e 将参数传递给 am instrument：

adb shell am instrument -e androidx.benchmark.profiling.mode StackSampling -w com.example.macrobenchmark/androidx.benchmark.junit4.AndroidBenchmarkRunner

如需详细了解如何在持续集成环境中配置基准测试，请参阅在持续集成环境中运行基准测试

additionalTestOutputDir

配置在设备上保存 JSON 基准测试报告和性能分析结果的位置。

• 参数类型：文件路径字符串
• 默认为：测试 APK 的外部目录

androidx.benchmark.cpuEventCounter.enable（实验性）

统计 androidx.benchmark.cupEventCounter.events 中指定的 CPU 事件。需要 root 访问权限。

• 参数类型：布尔值
• 默认值：false

androidx.benchmark.cpuEventCounter.events（实验性）

指定要统计哪些类型的 CPU 事件。如需使用此参数，必须将 androidx.benchmark.cpuEventCounter.enable 设置为 true。

• 参数类型：以英文逗号分隔的字符串列表
• 可用选项：
  • Instructions
  • CPUCycles
  • L1DReferences
  • L1DMisses
  • BranchInstructions
  • BranchMisses
  • L1IReferences
  • L1IMisses
• 默认为：Instructions、CpuCycles、BranchMisses

androidx.benchmark.dryRunMode.enable

此参数可允许您在单个循环中运行基准测试，以验证基准测试是否正常运行。

也就是说：

• 不强制执行配置错误（例如，以便更轻松地在模拟器上运行常规正确性测试）
• 基准仅运行单个循环，无需预热
• 不会捕获测量结果和轨迹，以缩短运行时间

这会优先优化测试吞吐量和基准测试逻辑验证，而不是构建和衡量准确性。

• 参数类型：布尔值
• 默认为：false

androidx.benchmark.iterations

替换时间驱动的迭代计数目标，以帮助确保工作量一致。这通常只有在启用性能分析的情况下才有用，有助于确保在比较不同实现/运行时，在性能分析跟踪中执行的工作量一致。在其他情况下，这可能会降低测量结果的准确性或稳定性。

• 参数类型：整数
• 默认为：未指定

androidx.benchmark.junit4.SideEffectRunListener

如果在运行基准测试期间执行了不相关的后台工作，基准测试结果可能会不一致。

如需在基准测试期间停用后台工作，请将 listener 插桩参数类型设置为 androidx.benchmark.junit4.SideEffectRunListener。

• 参数类型：字符串
• 可用选项：
  • androidx.benchmark.junit4.SideEffectRunListener
• 默认为：未指定

androidx.benchmark.output.enable

允许将 JSON 结果文件写入外部存储空间

• 参数类型：布尔值
• 默认为：true

androidx.benchmark.profiling.mode

允许在运行基准测试时捕获跟踪文件。如需了解可用的选项，请参阅对 Microbenchmark 进行性能分析。

请注意，某些 Android OS 版本不支持方法跟踪，而不会影响后续测量。Microbenchmark 会抛出异常来防止这种情况，因此请仅在安全的情况下使用默认参数来捕获方法轨迹。请参阅问题 316174880。

• 参数类型：字符串
• 可用选项：
  • MethodTracing
  • StackSampling
  • None
• 默认为：MethodTracing 的安全版本，仅在设备能够在不影响测量的情况下捕获方法轨迹时才会捕获方法轨迹。

androidx.benchmark.suppressErrors

接受以逗号分隔的错误列表，以供转换为警告。

• 参数类型：字符串列表
• 可用选项：
  • DEBUGGABLE
  • LOW-BATTERY
  • EMULATOR
  • CODE-COVERAGE
  • UNLOCKED
  • SIMPLEPERF
  • ACTIVITY-MISSING
• 默认为：一个空列表