閾値とアラート
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を使用する場合、以下のように記述できます:
🐰 フィーチャーブランチで作業する際は、ベースであるStart Point Branchから既存のThresholdsをコピーしたい場合があります。これは、the
--start-point-clone-thresholds
flagを使用して可能です。ただし、--thresholds-reset
フラグは、明示的に指定されていないすべてのクローンされたThresholdsも削除します。
複数の閾値
同じbencher run
の呼び出しで複数の閾値を作成することが可能です。
複数の閾値を指定する場合、各閾値で同じオプションを使用する必要があります。
特定の閾値に対してオプションを無視したい場合は、アンダースコア(_
)を使用します。
例えば、2つの閾値を使用したい場合、
一つはレイテンシの測定用、もう一つはスループットの測定用とすると、
レイテンシの測定には上限値を設定し、
スループットの測定には下限値を設定することが考えられます。
したがって、レイテンシの測定には--threshold-lower-boundary _
を使用し、
スループットの測定には--threshold-upper-boundary _
を使用すると良いでしょう。
このように書くことができます:
--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_ignore
BencherIgnore
-bencher-ignore
例えば、ベンチマークが my_flaky_benchmark
という名前の場合、それを my_flaky_benchmark_bencher_ignore
に変更することで、
その特定のベンチマークの警告を無視することができます。
無視されたベンチマークも既存のしきい値と照らし合わせてチェックされます。
しかし、それに対する警告は生成されません。
無視されたベンチマークのメトリックは引き続き保存されます。
my_flaky_benchmark_bencher_ignore
の結果は、ベンチマーク my_flaky_benchmark
として引き続き保存されます。
サフィックスを削除して元のベンチマーク名に戻すと、以前の状態から再開できます。
🐰 おめでとうございます!閾値とアラートについてすべて学びました! 🎉