指标名称预期文件

Fuchsia 的性能测试结果报告基础架构针对每个性能测试可能生成的指标名称，提供了一组已签入的预期值。这也称为指标名称许可名单。此功能已在 https://fxbug.dev/42056406 中添加。

如果性能测试生成的一组指标与测试的预期文件中所列的指标不匹配，则测试在运行时会失败。这意味着，如果测试发生更改，导致其生成的一组指标也发生更改，则必须更新其预期文件以保持一致。

对于 fuchsia.git 中的测试，预期文件位于 src/tests/end_to_end/perf/expected_metric_names/ 中。

所有新的性能测试（包括所有基于 Python 的性能测试）都需要预期文件。

预期福利

  • 预期文件旨在帮助保持指标命名的一致性。它们应能更轻松地检查指标的命名，并提供一种通过 OWNERS 检查来强制执行检查的方法。

  • 预期文件应能让测试作者更轻松地查看其他使用的指标名称，以便进行比较，因为该列表将签入代码库。

  • 通过预期文件，您可以更轻松地了解特定 CL 的生成指标列表发生了哪些变化。它们可让开发者确保 CL 没有意外移除或重命名指标。

  • 预期文件用于检查添加的指标数量。这非常有用，因为添加大量指标会产生费用。

  • 通过预期文件，可以更轻松地确保测试生成的一组指标具有确定性。指标可以动态生成，并且有多种生成方式。这意味着，如果不进行预期检查，测试的一组指标可能会是不确定的。这是不理想的，因为这会导致 CI build 生成的数据中出现随机缺口。

如何更新预期文件

更新测试的预期文件的一种方法是，在本地运行测试时设置环境变量 FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR，并使用如下调用：

fx test --e2e -o perf_publish_example_test \
    --env FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR=$(pwd)/src/tests/end_to_end/perf/expected_metric_names/

设置此环境变量后，测试会将更新后的预期文件写入环境变量指定的目录。请注意，这不会保留预期文件中的可选指标名称。

如果未设置此环境变量，则当测试生成的指标与预期文件中列出的指标不匹配时，测试会报告错误并打印差异。如有必要，您可以根据错误消息中的差异手动更新预期文件。

如何添加预期文件

如果您要添加新的性能测试，可以按照以下步骤为其添加预期文件。

对于使用 fuchsia_component_perf_test GN 模板的测试，步骤包括手动创建占位符预期文件：

  1. 在 src/tests/end_to_end/perf/expected_metric_names/ 中创建预期文件的空占位版本。

  2. 在测试的 GN 声明（即 fuchsia_component_perf_test GN 模板调用）中添加 expected_metric_names_filepath 实参。

  3. 如上所述，在本地运行测试并设置 FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR，以生成文件内容。

对于使用 python_perf_test GN 模板的测试，预期文件名在 GN 和测试代码中都有指定，因此可以按照以下步骤操作，避免手动创建占位符文件带来的不便：

  1. 在 Python 测试代码中，通过 expected_metric_names_filename 实参将名称传递给 publish_fuchsiaperf()。

  2. 在测试的 GN 声明（即 python_perf_test GN 模板调用）中设置 expected_metric_names_filepaths = []。

  3. 如上所述，使用 FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR 集在本地运行测试，以生成该文件。

  4. 将 expected_metric_names_filepaths 设置为测试的 GN 声明中预期文件的实际列表。

  5. 使用 git add src/tests/end_to_end/perf/expected_metric_names/ 将预期文件添加到 Git 签出中。

如果测试有多个预期文件，这些针对 python_perf_test 的步骤也适用。

可以先将文件添加到 BUILD.gn 文件中，但如果该文件不存在，GN 构建将会失败。

可选指标

预期文件可能包含带有后缀 [optional] 的条目。允许在测试的输出中缺少这些指标。这样，指标就可以是特定于架构或特定于机器的。应添加注释说明这些指标为何是可选的。（注释行以“#”开头。）

这还允许指标在是否生成方面具有不确定性。不过，如果指标不确定，通常会被视为应修复的 bug。

停用指标

如果某个指标处于停用状态，并且代码在当前状态下永远不会生成该指标，那么最好将其从列表中移除或注释掉，而不是将其标记为可选。否则，当指标重新启用时，我们可能会忘记移除 [optional] 标记，这意味着如果指标后来丢失，我们将不会注意到。

跳过指标的总结

默认情况下，使用 Python perf_publish 库时，发布的 fuchsiaperf 文件是汇总版本。

此总结会执行两项值得注意的操作：

  • 我们将每个 fuchsiaperf 条目中的第一个值视为预热运行并将其舍弃。
  • 同一测试用例可能存在多个条目（对应于多次进程运行），在这种情况下，我们会将它们合并。

将此操作作为后处理步骤执行具有以下优势：

  • 这样一来，就不需要在上游（在 C++ perftest 库或类似的其他语言库中）或下游消费者中实现此处理。
  • 总结性 fuchsiaperf 文件比“原始数据”fuchsiaperf 文件小得多，因此更易于管理。
  • “原始数据”fuchsiaperf 文件仍可供希望分析原始数据的任何人使用。

不过，在某些情况下，这可能并不理想：为了保留初始迭代的时间，而不是舍弃它们，或者为了允许将标准差报告给 Chromeperf 并将其显示在图表中。

因此，您可以通过在指标名称预期文件顶部添加 [no-summarize-metrics] 来针对整个文件关闭总结功能，也可以通过在预期文件中向指标的条目添加后缀 [no-summarize] 来针对单个指标关闭总结功能。