閾値とアラート
Thresholdsは、Bencherを使用してパフォーマンスの退行を検出する方法です。Thresholdは、次のユニークな組み合わせに割り当てられます：Branch、Testbed、およびMeasure。Thresholdは特定のTestを使用してパフォーマンスの退行を検出します。Testとそのパラメータの組み合わせはModelと呼ばれます。Modelは、Lower Boundary、Upper Boundary、またはその両方を持っていなければなりません。
- Lower Boundary
- Lower Boundaryは、より小さい値がパフォーマンスの退行を示す場合、例えばThroughput Measureの場合に使用されます。
- Upper Boundary
- Upper Boundaryは、より大きい値がパフォーマンスの退行を示す場合、例えばLatency Measureの場合に使用されます。
各BoundaryはBoundary Limitを計算するために使用されます。その後、すべての新しいMetricは各Boundary Limitに対してチェックされます。新しいMetricがLower Boundary Limitを下回ったりUpper Boundary Limitを上回ったりすると、Alertが生成されます。
Continuous Benchmarking、すなわちCIでベンチマークを行う際にはThresholdsを作成したいでしょう。bencher run CLIサブコマンドを使用すると、the --branch optionでBranchを、the --testbed optionでTestbedを既に指定しますので、指定する必要がある唯一の次元はMeasureであり、--threshold-measureオプションを使用します。そのMeasureに使用するTestを--threshold-testオプションで指定できます。--threshold-min-sample-size、--threshold-max-sample-size、および--threshold-windowオプションを使用して、Testで使用されるデータを制御できます。最後に、--threshold-lower-boundaryと--threshold-upper-boundaryオプションを使用して、Lower BoundaryとUpper Boundaryを設定できます。指定されていないすべてのModelを削除したい場合は、--thresholds-resetフラグでそれを行うことができます。
- Thresholdが存在しない場合は、自動的に作成されます。
- Thresholdが存在し、指定されたModelが同じ場合、Modelは無視されます。
- Thresholdが存在し、指定されたModelが異なる場合、新しいModelがThresholdのために作成されます。
- 既存のThresholdがあり、リセットされる場合、現在のModelはThresholdから削除されます。
例えば、a Student’s t-test Testを使用して、64の最大サンプルサイズと0.99のUpper Boundaryで、Latency MeasureにのみThresholdを使用する場合、以下のように記述できます:
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🐰 フィーチャーブランチで作業する際は、ベースであるStart Point Branchから既存のThresholdsをコピーしたい場合があります。これは、the
--start-point-clone-thresholdsflagを使用して可能です。ただし、--thresholds-resetフラグは、明示的に指定されていないすべてのクローンされたThresholdsも削除します。
複数の閾値
同じbencher runの呼び出しで複数の閾値を作成することが可能です。
複数の閾値を指定する場合、各閾値で同じオプションを使用する必要があります。
特定の閾値に対してオプションを無視したい場合は、アンダースコア（_）を使用します。
例えば、2つの閾値を使用したい場合、
一つはレイテンシの測定用、もう一つはスループットの測定用とすると、
レイテンシの測定には上限値を設定し、
スループットの測定には下限値を設定することが考えられます。
したがって、レイテンシの測定には--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>
指定されたテストを使用してパフォーマンスの退行を検出します。
いくつかの異なるテストが利用可能です：
- Static (
static) - Percentage (
percentage) - z-score (
z_score) - t-test (
t_test) - Log Normal (
log_normal) - Interquartile Range (
iqr) - Delta Interquartile Range (
delta_iqr)
例えば、スチューデントのt検定を使用してしきい値を設定するには、--threshold-test t_testと書きます。
スタティック
スタティックテスト (static) は最も単純なテストです。
新しいメトリックが設定された下限境界を下回るか、上限境界を上回るとアラートが生成されます。
つまり、下限/上限境界は明示的な下限/上限の制限です。
下限、上限、またはその両方を設定する必要があります。
スタティックテストは、メトリックの値がすべてのベンチマークで一定の範囲内にとどまるべき場合に最適に機能します。
例えば、コードカバレッジなどです。
-
スタティック下限境界
- スタティックテストの下限境界は任意の浮動小数点数にできます。 より小さい値がパフォーマンスの低下を示す場合に使用されます。 下限境界は、両方が指定されている場合、上限境界以下でなければなりません。
- 例えば、下限境界を
100に設定したスタティックテストがある場合、 下限境界の制限も同様に100となり、100未満の値はアラートを生成します。
-
スタティック上限境界
- スタティックテストの上限境界は任意の浮動小数点数にできます。 より大きい値がパフォーマンスの低下を示す場合に使用されます。 上限境界は、両方が指定されている場合、下限境界以上でなければなりません。
- 例えば、上限境界を
100に設定したスタティックテストがある場合、 上限境界の制限も同様に100となり、100より大きい値はアラートを生成します。
パーセンテージ
パーセンテージテスト（percentage）は最もシンプルな統計テストです。 新しいメトリックが平均の特定のパーセンテージ（下限）よりも低い場合、または平均の特定のパーセンテージ（上限）よりも高い場合、アラートが生成されます。 下限、上限、またはその両方を設定する必要があります。 パーセンテージテストは、メトリックの値が既知の適正な範囲内にあるべき場合に最適です。
-
パーセンテージ下限
- パーセンテージテストの下限は、少なくともゼロ以上のパーセンテージを小数形式で指定できます（例:
10%の場合は0.10を使用）。これは、より小さな値がパフォーマンスの低下を示す場合に使用されます。 - 例えば、下限を
0.10に設定したパーセンテージテストがあり、履歴メトリックの平均が100である場合、下限限界は90となり、90未満の値はアラートを生成します。
- パーセンテージテストの下限は、少なくともゼロ以上のパーセンテージを小数形式で指定できます（例:
-
パーセンテージ上限
- パーセンテージテストの上限は、少なくともゼロ以上のパーセンテージを小数形式で指定できます（例:
10%の場合は0.10を使用）。これは、より大きな値がパフォーマンスの低下を示す場合に使用されます。 - 例えば、上限を
0.10に設定したパーセンテージテストがあり、履歴メトリックの平均が100である場合、上限限界は110となり、110より大きい値はアラートを生成します。
- パーセンテージテストの上限は、少なくともゼロ以上のパーセンテージを小数形式で指定できます（例:
z-score
zスコアテスト (z_score) は、新しいメトリクスが過去のメトリクスの平均からどれくらいの標準偏差 (σ) 離れているかをzスコアを用いて測定します。
zスコアテストは以下の条件で最も効果的に機能します：
- ベンチマーク実行間に極端な差がない
- ベンチマーク実行が完全に独立している
- 単一のベンチマーク実行の反復数が過去のメトリクスの10%未満である
- 少なくとも30の過去のメトリクスが存在する（最小サンプルサイズ >= 30）
zスコアテストでは、標準偏差は小数の累積パーセンテージとして表されます。 新しいメトリクスが過去のメトリクスのある左側の累積パーセンテージ（下限）以下の場合や、ある右側の累積パーセンテージ（上限）以上の場合にアラートが生成されます。 下限、上限、またはその両方を設定する必要があります。
-
zスコア下限
- zスコアテストの下限は、
0.5から1.0の間の任意の正の小数に設定できます。0.5は平均を示し、1.0はすべての左側の可能な値（-∞）を示します。 これは、より小さな値がパフォーマンスの低下を示す場合に使用されます。 - 例えば、下限が
0.977のzスコアテストを使用し、過去のメトリクスの平均が100、標準偏差が10であった場合、下限は80.05になり、80.05未満の値はアラートを生成します。
- zスコアテストの下限は、
-
zスコア上限
- zスコアテストの上限は、
0.5から1.0の間の任意の正の小数に設定できます。0.5は平均を示し、1.0はすべての右側の可能な値（∞）を示します。 これは、より大きな値がパフォーマンスの低下を示す場合に使用されます。 - 例えば、上限が
0.977のzスコアテストを使用し、過去のメトリクスの平均が100、標準偏差が10であった場合、上限は119.95になり、119.95を超える値はアラートを生成します。
- zスコアテストの上限は、
t-test
t検定テスト (t_test) は、新しいメトリックが過去のメトリックの平均値を上回るか下回るかの信頼区間 (CI) をスチューデントのt検定を使用して測定します。
t検定テストが最も効果的なのは次のような場合です：
- ベンチマークラン間に極端な差がない
- ベンチマークランが完全に独立している
- 単一のベンチマークランの反復回数が過去のメトリックの10%未満である
t検定テストでは、信頼区間は小数の信頼パーセンテージで表されます。 新しいメトリックが過去のメトリックの特定の左側信頼パーセンテージ（下限）以下、または右側信頼パーセンテージ（上限）以上である場合、アラートが生成されます。下限、上限、またはその両方が設定されていなければなりません。
-
t-test 下限
- t検定テストの下限は、
0.5から1.0の任意の正の小数でかまいません。0.5は平均を表し、1.0はすべての可能な左側の値 (-∞) を表します。 これは、より小さい値がパフォーマンスの退行を示す場合に使用します。 - 例えば、下限が
0.977のt検定テストを使用し、平均が100で標準偏差が10の25の過去のメトリックがある場合、下限は78.96となり、78.96以下の値はアラートを生成します。
- t検定テストの下限は、
-
t-test 上限
- t検定テストの上限は、
0.5から1.0の任意の正の小数でかまいません。0.5は平均を表し、1.0はすべての可能な右側の値 (∞) を表します。 これは、より大きい値がパフォーマンスの退行を示す場合に使用します。 - 例えば、上限が
0.977のt検定テストを使用し、平均が100で標準偏差が10の25の過去のメトリックがある場合、上限は121.04となり、121.04以上の値はアラートを生成します。
- t検定テストの上限は、
対数正規分布
対数正規検定 (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 の一定の倍数（下限境界）よりも下か、または一定の倍数（上限境界）よりも上である場合、アラートが生成されます。下限境界、上限境界、または両方を設定する必要があります。
-
四分位範囲下限境界
- 四分位範囲テストの下限境界は、ゼロ以上の任意の倍率にすることができます（例:
2.0を2xとして使用）。これは、より小さい値がパフォーマンスの低下を示す場合に使用されます。 - 例えば、下限境界を
2.0に設定した四分位範囲テストがあり、過去のメトリックの中央値が100、四分位範囲が10だった場合、下限境界は80となり、80未満の値はアラートを生成します。
- 四分位範囲テストの下限境界は、ゼロ以上の任意の倍率にすることができます（例:
-
四分位範囲上限境界
- 四分位範囲テストの上限境界は、ゼロ以上の任意の倍率にすることができます（例:
2.0を2xとして使用）。これは、より大きい値がパフォーマンスの低下を示す場合に使用されます。 - 例えば、上限境界を
2.0に設定した四分位範囲テストがあり、過去のメトリックの中央値が100、四分位範囲が10だった場合、上限境界は120となり、120を超える値はアラートを生成します。
- 四分位範囲テストの上限境界は、ゼロ以上の任意の倍率にすることができます（例:
デルタ四分位範囲
デルタ四分位範囲テスト (delta_iqr) は、新しいメトリックが履歴メトリックの中央値よりどれだけ多くの平均変化率(Δ)四分位範囲 (IQR) を超えているかを測定します。新しいメトリックがΔIQRの一定倍以下（下限）または一定倍以上（上限）である場合、アラートが生成されます。下限、上限、またはその両方を設定する必要があります。
-
デルタ四分位範囲の下限
- デルタ四分位範囲テストの下限は、ゼロ以上の任意の乗数に設定できます（例：
2.0を使用して2x）。これは、より小さい値がパフォーマンスの低下を示す場合に使用されます。 - 例として、デルタ四分位範囲テストの下限が
2.0に設定され、履歴メトリックの中央値が100、四分位範囲が10、平均デルタ四分位範囲が0.2（20%）の場合、下限は60となり、60未満の値はアラートを生成します。
- デルタ四分位範囲テストの下限は、ゼロ以上の任意の乗数に設定できます（例：
-
デルタ四分位範囲の上限
- デルタ四分位範囲テストの上限は、ゼロ以上の任意の乗数に設定できます（例：
2.0を使用して2x）。これは、より大きい値がパフォーマンスの低下を示す場合に使用されます。 - 例として、デルタ四分位範囲テストの上限が
2.0に設定され、履歴メトリックの中央値が100、四分位範囲が10、平均デルタ四分位範囲が0.2（20%）の場合、上限は140となり、140を超える値はアラートを生成します。
- デルタ四分位範囲テストの上限は、ゼロ以上の任意の乗数に設定できます（例：
--threshold-min-sample-size <SAMPLE_SIZE>
オプションとして、テストを実行するために必要なメトリクスの最小数を指定します。
この最小数に達していない場合、テストは実行されません。
指定したサンプルサイズは2以上でなければなりません。
the --threshold-max-sample-size optionが設定されている場合、
指定したサンプルサイズは--threshold-max-sample-size以下でなければなりません。
このオプションはStatic（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）テストと併用することはできません。
例えば、4週間または2419200秒のウィンドウでしきい値を使用するには、--threshold-window 2419200と記述します。
4週間より古いメトリクスがあれば、それらは除外されます。
逆に、すべてのメトリクスが過去4週間以内であれば、それらはすべて含まれます。
--threshold-lower-boundary <BOUNDARY>
下限を指定します。下限に関する制約は使用しているテストに依存します。下限、上限、またはその両方を指定する必要があります。
詳細については、使用している特定のテストのドキュメントを参照してください：
--threshold-upper-boundary <BOUNDARY>
上限境界を指定します。上限境界の制約は使用するテストによって異なります。下限境界、上限境界、またはその両方を指定する必要があります。
詳細については、ご使用のテストの特定のドキュメントを参照してください：
---thresholds-reset
指定されたブランチとテストベッドの、すべての指定されていないしきい値をリセットします。しきい値が既に存在し、指定されていない場合、その現在のモデルは削除されます。
例えば、mainブランチとlocalhostテストベッドに2つのしきい値がある場合：
bencher runサブコマンドでlatencyメジャーのみが指定され、--thresholds-resetが使用されると、
throughputメジャーはそのモデルが削除されます。
--err
警告が生成された場合にエラーを発生させるオプションです。 新しいメトリックが下限界値を下回るか、上限界値を超えた場合に警告が生成されます。
警告の抑制
特定のベンチマークに対する警告を抑制したい場合があります。 そのための最良の方法は、ベンチマーク名に以下の特殊サフィックスのいずれかを追加することです:
_bencher_ignoreBencherIgnore-bencher-ignore
例えば、ベンチマークが my_flaky_benchmark という名前の場合、それを my_flaky_benchmark_bencher_ignore に変更することで、
その特定のベンチマークの警告を無視することができます。
無視されたベンチマークも既存のしきい値と照らし合わせてチェックされます。
しかし、それに対する警告は生成されません。
無視されたベンチマークのメトリックは引き続き保存されます。
my_flaky_benchmark_bencher_ignore の結果は、ベンチマーク my_flaky_benchmark として引き続き保存されます。
サフィックスを削除して元のベンチマーク名に戻すと、以前の状態から再開できます。
🐰 おめでとうございます！閾値とアラートについてすべて学びました！ 🎉