阈值与警报

Thresholds 是你用 Bencher 捕捉性能回归的方式。 Threshold 被分配给一个唯一的组合： Branch，Testbed 和 Measure。 Threshold 使用特定的 Test 来检测性能回归。 测试及其参数的组合称为一个模型。 一个模型必须有一个下界，上界，或两者都有。

• 下界
  • 当较小的数值表明性能回归时，使用下界，比如在吞吐量度量中。
• 上界
  • 当较大的数值表明性能回归时，使用上界，比如在延迟度量中。

每个边界用于计算边界限制。 然后每个新的 Metric 都会与每个边界限制进行比较。 当新的 Metric 低于下界限制或高于上界限制时，会生成警报。

当 [持续基准测试]时，即在持续集成（CI）中进行基准测试时，你会想创建阈值。 使用 bencher run CLI 子命令， 你已经用 the --branch option 指定了一个 Branch， 并用 the --testbed option 指定了一个 Testbed。 所以你唯一需要指定的其他维度是测量，用 --threshold-measure 选项。 然后你可以使用 --threshold-test 选项来指定该测量使用的测试。 --threshold-min-sample-size，--threshold-max-sample-size，和 --threshold-window 选项 允许你控制测试使用的数据。 最后，--threshold-lower-boundary 和 --threshold-upper-boundary 选项 允许你设置下界和上界。 如果你想移除所有未指定的模型，可以使用 --thresholds-reset 标志。

• 如果 Threshold 不存在，它将为你创建。
• 如果 Threshold 存在且指定的模型相同，则模型将被忽略。
• 如果 Threshold 存在且指定的模型不同，则为 Threshold 创建一个新模型。
• 如果 Threshold 存在并被重置，则当前模型将从 Threshold 中移除。

例如，只用一个 Student’s t-test 测试为延迟度量设置 Threshold， 最大样本大小为 64，上界为 0.99，你可以写成这样：

bencher run \
--project save-walter-white-1234abcd \
--branch main \
--testbed localhost \
--threshold-measure latency \
--threshold-test t_test \
--threshold-max-sample-size 64 \
--threshold-upper-boundary 0.99 \
--thresholds-reset \
--err \
--adapter json \
bencher mock

🐰 在处理功能分支时，您可能想从基准 起点 Branch 复制现有的 Thresholds。 可以通过 the --start-point-clone-thresholds flag 实现。 注意，--thresholds-reset 标志仍会移除任何未明确指定的克隆阈值。

多重阈值

可以在同一次bencher run调用中创建多个阈值。 指定多个阈值时，必须为每个阈值使用相同的选项。 要忽略特定阈值的某个选项，请使用下划线 (_)。

例如，如果您只想使用两个阈值，一个用于延迟度量，一个用于吞吐量度量，那么您可能想为延迟度量设置上限，为吞吐量度量设置下限。因此，您将为延迟度量使用 --threshold-lower-boundary _，为吞吐量度量使用 --threshold-upper-boundary _。您可以这样写：

bencher run \
--project save-walter-white-1234abcd \
--branch main \
--testbed localhost \
--threshold-measure latency \
--threshold-test t_test \
--threshold-max-sample-size 64 \
--threshold-lower-boundary _ \
--threshold-upper-boundary 0.99 \
--threshold-measure throughput \
--threshold-test t_test \
--threshold-max-sample-size 64 \
--threshold-lower-boundary 0.99 \
--threshold-upper-boundary _ \
--thresholds-reset \
--err \
--adapter json \
bencher mock --measure latency --measure throughput

--threshold-measure <MEASURE>

使用指定的度量名称、标识符或UUID作为阈值。如果指定的值是名称或标识符且度量不存在，将会为您创建它。但是，如果指定的值是UUID，那么度量必须已经存在。

例如，要为延迟度量使用阈值，你可以输入--threshold-measure latency。

--threshold-test <TEST>

使用指定的测试来检测性能回归。

有几种不同的测试可用：

• 百分比 (percentage)
• z分数 (z_score)
• t检验 (t_test)
• 对数正态 (log_normal)
• 四分位间距 (iqr)
• 差异四分位间距 (delta_iqr)
• 静态 (static)

例如，要使用包含学生t检验的阈值，你可以写 --threshold-test t_test。

百分比

百分比测试（percentage）是最简单的统计测试之一。 如果新的指标值低于历史指标均值的某个百分比（下限）或高于某个百分比（上限），则会生成警报。 必须设定下限、上限或两者之一。 当指标值应保持在已知的良好范围内时，百分比测试效果最好。

• 百分比下限

  • 百分比测试的下限可以是任何大于或等于零的百分数，以小数形式表示（例如：使用 0.10 表示 10%）。 当较小的值表示性能下降时使用。
  • 例如，如果您有一个下限设为 0.10 的百分比测试，而历史指标的均值为 100，则下限为 90，任何小于 90 的值都会生成警报。

• 百分比上限

  • 百分比测试的上限可以是任何大于或等于零的百分数，以小数形式表示（例如：使用 0.10 表示 10%）。 当较大的值表示性能下降时使用。
  • 例如，如果您有一个上限设为 0.10 的百分比测试，而历史指标的均值为 100，则上限为 110，任何大于 110 的值都会生成警报。

z-score

z-score 测试（z_score）测量一个新指标相对于你历史指标的均值的标准差数量（σ），使用z-score。

z-score 测试在以下情况下效果最佳：

• 基准测试运行之间没有极端差异
• 基准测试运行完全独立
• 单次基准测试运行的迭代次数少于历史指标的 10%
• 至少有 30 个历史指标（最小样本量 >= 30）

对于 z-score 测试，标准差以十进制累积百分比表示。 如果一个新指标在你的历史指标的某个左侧累积百分比（下界）以下或某个右侧累积百分比（上界）以上，系统将生成警报。必须设置下界、上界或两者之一。

• z-score 下界

  • z-score 测试下界可以是 0.5 和 1.0 之间的任何正小数。0.5 表示均值，1.0 表示所有可能的左侧值（-∞）。它用于当较小的值表示性能下降时。
  • 例如，如果你使用一个下界为 0.977 的 z-score 测试，且你的历史指标的均值为 100，标准差为 10，则下界限制为 80.05，任何小于 80.05 的值将生成警报。

• z-score 上界

  • z-score 测试上界可以是 0.5 和 1.0 之间的任何正小数。0.5 表示均值，1.0 表示所有可能的右侧值（∞）。它用于当较大的值表示性能下降时。
  • 例如，如果你使用一个上界为 0.977 的 z-score 测试，且你的历史指标的均值为 100，标准差为 10，则上界限制为 119.95，任何大于 119.95 的值将生成警报。

t-test

t检验（t_test）使用斯图登特t检验测量一个指标高于或低于历史指标均值的置信区间（CI）有多大可能性。

t检验在以下情况下效果最佳：

• 基准测试运行之间没有极端差异
• 基准测试运行完全独立
• 单次基准测试运行的迭代次数少于历史指标的10%

对于t检验，置信区间通过小数表示为置信百分比。如果一个新指标低于某个左侧置信百分比（下限）或高于某个右侧置信百分比（上限）的历史指标，则会生成警报。必须设置下限、上限或两者。

• t检验下限

  • t检验下限可以是0.5和1.0之间的任何正小数。0.5表示均值，1.0表示所有可能的左侧值（-∞）。当较小的值表示性能回退时使用。
  • 例如，如果使用t检验并设置下限为0.977，且有25个历史指标均值为100，标准差为10，则下限为78.96，低于78.96的任何值都会生成警报。

• t检验上限

  • t检验上限可以是0.5和1.0之间的任何正小数。0.5表示均值，1.0表示所有可能的右侧值（∞）。当较大的值表示性能回退时使用。
  • 例如，如果使用t检验并设置上限为0.977，且有25个历史指标均值为100，标准差为10，则上限为121.04，高于121.04的任何值都会生成警报。

对数正态分布

对数正态测试（log_normal）用于测量一个新指标高于或低于历史指标的中心位置的可能性，使用对数正态分布。

对数正态测试在以下情况下效果最佳：

• 基准测试运行彼此完全独立
• 单次基准测试运行的迭代次数少于历史指标的10%
• 所有数据为正（负数的自然对数为未定义）

对于对数正态测试，可能性以小数百分比表示。 如果一个新指标低于历史指标的某个左侧百分比（下界） 或高于某个右侧百分比（上界），则会生成警报。 必须设置下界、上界或两者之一。

• 对数正态下界

  • 对数正态测试下界可以是0.5到1.0之间的任何正小数。 其中0.5代表中心位置，1.0代表所有可能的左侧值 (-∞)。 用于当较小的值表明性能退化的情况。
  • 例如，如果您使用了下界为0.977的对数正态测试， 并且您有25个集中在100的历史指标和一个之前在200的离群值， 则下界限制为71.20， 任何小于71.20的值都会生成警报。

• 对数正态上界

  • 对数正态测试上界可以是0.5到1.0之间的任何正小数。 其中0.5代表中心位置，1.0代表所有可能的右侧值 (∞)。 用于当较大的值表明性能退化的情况。
  • 例如，如果您使用了上界为0.977的对数正态测试， 并且您有25个集中在100的历史指标和一个之前在200的离群值， 则上界限制为134.18， 任何大于134.18的值都会生成警报。

四分位距

四分位距测试 (iqr) 测量一个新的指标在历史指标的中位数之上或之下多少个四分位距 (IQR) 的倍数。如果一个新的指标低于中位数的 IQR 的某个倍数（下边界）或高于中位数的 IQR 的某个倍数（上边界），将生成一个警报。必须设置下边界、上边界或两者之一。

• 四分位距下边界

  • 四分位距测试下边界可以是任何大于或等于零的倍数（例如：使用 2.0 表示 2倍）。当较小的值表示性能回归时使用。
  • 例如，如果您有一个四分位距测试，下边界设置为 2.0，而您的历史指标中位数为 100，四分位距为 10，则下边界限制将是 80，任何小于 80 的值将生成一个警报。

• 四分位距上边界

  • 四分位距测试上边界可以是任何大于或等于零的倍数（例如：使用 2.0 表示 2倍）。当较大的值表示性能回归时使用。
  • 例如，如果您有一个四分位距测试，上边界设置为 2.0，而您的历史指标中位数为 100，四分位距为 10，则上边界限制将是 120，任何大于 120 的值将生成一个警报。

Delta四分位距

Delta四分位距测试（delta_iqr）用于测量一个新的指标在历史指标的中位数之上或之下超出平均百分比变化（Δ）四分位距（IQR）的倍数。如果一个新的指标低于中位数的ΔIQR的某个倍数（下限）或高于中位数的ΔIQR的某个倍数（上限），则会生成一个警报。必须设置下限、上限或两者。

• Delta四分位距下限

  • Delta四分位距测试的下限可以是大于或等于零的任何倍数（例如：使用2.0代表2x）。当较小的值表示性能回归时使用。
  • 例如，如果您有一个Delta四分位距测试，其下限设置为2.0，并且您的历史指标的中位数为100，四分位距为10，平均delta四分位距为0.2（20%），则下限为60，任何小于60的值都会生成警报。

• Delta四分位距上限

  • Delta四分位距测试的上限可以是大于或等于零的任何倍数（例如：使用2.0代表2x）。当较大的值表示性能回归时使用。
  • 例如，如果您有一个Delta四分位距测试，其上限设置为2.0，并且您的历史指标的中位数为100，四分位距为10，平均delta四分位距为0.2（20%），则上限为140，任何大于140的值都会生成警报。

静态

静态测试（static）是最简单的测试。 如果一个新的指标低于设定的下限或高于设定的上限，将会生成一个警报。 也就是说，下限/上限是一个明确的下限/上限界限。 必须设置下限、上限或两者之一。 当指标的值在所有基准中应保持在一个恒定范围内时，例如代码覆盖率，静态测试效果最佳。

🐰 如果您希望为每个基准测试设置不同的静态下限/上限， 则应使用百分比测试 (percentage) 将下限/上限设置为 0.0 并将最大样本大小设置为 2。

• 静态下限

  • 静态测试下限可以是任意的浮点数。 当一个较小的值表示性能退化时使用。 如果同时指定上下限，下限必须小于或等于上限。
  • 例如，如果您有一个下限设置为100的静态测试， 那么下限界限同样为100， 任何小于100的值都会触发一个警报。

• 静态上限

  • 静态测试上限可以是任意的浮点数。 当一个较大值表示性能退化时使用。 如果同时指定上下限，上限必须大于或等于下限。
  • 例如，如果您有一个上限设置为100的静态测试， 那么上限界限同样为100， 任何大于100的值都会触发一个警报。

--threshold-min-sample-size <SAMPLE_SIZE>

可选地指定运行测试所需的最小指标数量。 如果未达到此最小值，测试将不会运行。 指定的样本大小必须大于或等于 2。 如果还设置了 --threshold-max-sample-size 选项， 那么指定的样本大小必须小于或等于 --threshold-max-sample-size。 此选项不能与静态 (static) 测试一起使用。

例如，要使用最小样本大小为 10 的阈值， 您可以编写 --threshold-min-sample-size 10。 如果指标少于 10，测试将不会运行。 反之，如果有 10 个或更多指标，测试将会运行。

--threshold-max-sample-size <SAMPLE_SIZE>

可选项，指定运行测试时使用的度量的最大数量。 如果超过此最大值，最旧的度量将被忽略。 指定的样本大小必须大于或等于 2。 如果同时设置了--threshold-min-sample-size 选项，那么指定的样本大小必须大于或等于 --threshold-min-sample-size。 此选项不能与静态（static）测试一起使用。

例如，要使用最大样本大小为 100 的阈值，可以写作 --threshold-max-sample-size 100。 如果存在超过 100 个度量，则只有最近的 100 个度量会被包含。 相反，如果有 100 个或更少的度量，则所有度量都会被包含。

--threshold-window <WINDOW>

可以选择性地指定用于执行测试的指标时间窗口，以秒为单位。 指定的窗口必须大于0。 此选项不能与静态（static）测试一起使用。

例如，要使用一个窗口为四周或2419200秒的阈值，你可以写作--threshold-window 2419200。 如果有任何指标早于四周，它们将被排除。 相反，如果所有指标都来自过去四周内，则它们都将被纳入。

--threshold-lower-boundary <BOUNDARY>

指定下限。 下限的约束取决于所使用的测试。 必须指定下限、上限或两者之一。

有关详细信息，请参阅您所使用测试的文档：

• Percentage Lower Boundary
• z-score Lower Boundary
• t-test Lower Boundary
• Log Normal Lower Boundary
• Interquartile Range Lower Boundary
• Delta Interquartile Range Lower Boundary
• Static Lower Boundary

--threshold-upper-boundary <BOUNDARY>

指定上限边界。上限边界的约束取决于所使用的测试。必须指定下限边界、上限边界或两者。

有关详细信息，请参阅您使用的特定测试的文档：

• 百分比上限边界
• z-分数上限边界
• t-检验上限边界
• 对数正态上限边界
• 四分位间距上限边界
• 增量四分位间距上限边界
• 静态上限边界

---thresholds-reset

重置给定分支和测试平台中所有未指定的阈值。如果一个阈值已存在但未被指定，其当前模型将被移除。

例如，如果在main分支和localhost测试平台中有两个阈值：

• main 分支，localhost 测试平台，latency 度量
• main 分支，localhost 测试平台，throughput 度量

如果在 bencher run 子命令中只指定了 latency 度量，并且使用了 --thresholds-reset， 那么 throughput 度量的模型将被移除。

--err

如果生成了警报，则可选择性地出错。 当新指标低于最低边界限或高于最高边界限时，会生成警报。

抑制警报

有时抑制某个基准测试的警报可能很有用。 最好的方法是在该基准测试的名称中添加以下特殊后缀之一：

• _bencher_ignore
• BencherIgnore
• -bencher-ignore

例如，如果您的基准测试命名为 my_flaky_benchmark，那么将其重命名为 my_flaky_benchmark_bencher_ignore 将会忽略该特定基准测试以后的警报。 被忽略的基准测试仍会与现有的阈值进行检查。 但是，不会为其生成警报。 被忽略基准测试的指标仍会被存储。 my_flaky_benchmark_bencher_ignore 的结果仍将存储为基准测试 my_flaky_benchmark。 如果您删除后缀并返回到原来的基准测试名称，事情将会继续进行，正如您所暂停时的状态。

🐰 恭喜！你已经学习了所有关于阈值与警报的内容！🎉

继续前进：基准测试适配器 ➡