指标名称预期文件

Fuchsia 的用于报告性能测试结果的基础架构对于每个性能测试可能产生的指标名称都有一套预期结果。这也称为指标名称许可名单。这是在 https://fxbug.dev/42056406 中添加的。

如果性能测试生成的指标集与测试的预期文件中列出的指标不一致，测试将在运行时失败。这意味着，如果更改测试，使得测试生成的一组指标也发生变化，则必须更新其预期文件以保持一致。

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

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

预期优势

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

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

  • 预期文件应可让您更轻松地查看给定 CL 的所生成指标列表发生了哪些变化。它们可以让开发者确保 CL 不会意外移除或重命名指标。

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

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

如何更新预期文件

如需更新测试的预期文件，一种方法是在设置环境变量 FUCHSIA_EXPECTED_METRIC_NAMES_DEST_DIR 的情况下在本地运行测试，具体调用如下所示：

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

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

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

如何添加预期文件

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

对于使用 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. 将 expected_metric_names_filename 参数中的名称传递给 Python 测试代码中的 publish_fuchsiaperf()。

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

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

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

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

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

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

可选指标

预期文件可能包含后缀为 [optional] 的条目。测试的输出中可以不存在这些指标。这样一来，指标将可以特定于架构或特定于机器。应该对这些指标进行注释，说明为什么它们是可选项。（注释行以“#”开头。）

这也使得指标在生成与否方面具有不确定性。不过，具有不确定性的指标通常会被视为应该修复的 bug。

跳过指标汇总

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

本总结有两点值得一提：

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

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

  • 无需在上游（在 C++ Perftest 库或其他语言的类似库中）或下游使用方中实现此处理。
  • 摘要 fuchsiaperf 文件比“原始数据”fuchsiaperf 文件小得多，因此更易于管理。
  • 希望分析原始数据的人仍然可以使用“原始数据”fuchsiaperf 文件。

但在某些情况下，这可能是不可取的：保留初始迭代的时间而不是丢弃它们，或者允许向 Chromeperf 报告标准差并使其显示在图表中。

因此，可以通过在指标名称预期文件顶部添加 [no-summarize-metrics] 来关闭汇总功能。