指标名称预期文件

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. 将 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. 将 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++ 性能测试库或其他语言的类似库中）或下游使用方中实现此处理。
  • 摘要 fuchsiaperf 文件比“原始数据”fuchsiaperf 文件小得多，因此更易于管理。
  • 我们仍然可以向希望分析原始数据的任何人提供“原始数据”fuchsiaperf 文件。

不过，在某些情况下，这可能不适合：例如，保留初始迭代的运行时间，而不是将其舍弃，或者允许将标准差报告给 Chromeperf 并在图表中显示。

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