Seuils & Alertes
Les seuils sont la façon dont vous détectez les régressions de performance avec Bencher. Un seuil est attribué à une combinaison unique de : Branch, Testbed, et Measure. Un seuil utilise un Test spécifique pour détecter les régressions de performance. La combinaison d’un test et de ses paramètres est appelée un Modèle. Un modèle doit avoir une Limite Inférieure, une Limite Supérieure, ou les deux.
- Limite Inférieure
- Une Limite Inférieure est utilisée lorsqu’une valeur plus petite indiquerait une régression de performance, comme avec la Mesure de Débit.
- Limite Supérieure
- Une Limite Supérieure est utilisée lorsqu’une valeur plus grande indiquerait une régression de performance, comme avec la Mesure de Latence.
Chaque limite est utilisée pour calculer une Limite de Seuil. Ensuite, chaque nouvelle Métrique est vérifiée par rapport à chaque Limite de Seuil. Une alerte est générée lorsqu’une nouvelle métrique est en dessous d’une Limite Inférieure de Seuil ou au-dessus d’une Limite Supérieure de Seuil.
Lors du [Benchmarking Continu], c’est-à-dire du benchmarking en CI, vous voudrez créer des seuils.
En utilisant la sous-commande CLI bencher run
,
vous spécifiez déjà une branche avec l’option --branch
et un Testbed avec l’option --testbed
.
Donc la seule autre dimension que vous devez spécifier est une Mesure, avec l’option --threshold-measure
.
Ensuite, vous pouvez utiliser l’option --threshold-test
pour spécifier le Test à utiliser pour cette Mesure.
Les options --threshold-min-sample-size
, --threshold-max-sample-size
, et --threshold-window
vous permettent de contrôler les données utilisées par le Test.
Enfin, les options --threshold-lower-boundary
et --threshold-upper-boundary
vous permettent de définir la Limite Inférieure et la Limite Supérieure.
Si vous souhaitez supprimer tous les modèles qui ne sont pas spécifiés,
vous pouvez le faire avec le drapeau --thresholds-reset
.
- Si le seuil n’existe pas, il sera créé pour vous.
- Si le seuil existe et que le modèle spécifié est le même, alors le modèle est ignoré.
- Si le seuil existe et que le modèle spécifié est différent, alors un nouveau modèle est créé pour le seuil.
- Si un seuil existe et qu’il est réinitialisé, alors le modèle actuel est retiré du seuil.
Par exemple, pour n’utiliser qu’un seuil pour la Mesure de Latence
en utilisant un test de Student
avec une taille d’échantillon maximale de 64
et une Limite Supérieure de 0.99
, vous pourriez écrire quelque chose comme ceci :
🐰 Lorsqu’on travaille avec des branches de fonctionnalités, vous pourriez vouloir copier les seuils existants à partir de la branche de base, Point de Départ. C’est possible avec le drapeau
--start-point-clone-thresholds
. Notez que le drapeau--thresholds-reset
retirera toujours les seuils clonés qui ne sont pas explicitement spécifiés.
Seuils Multiples
Il est possible de créer plusieurs seuils avec la même invocation de
bencher run
.
Lors de la spécification de plusieurs seuils, toutes les mêmes options doivent être utilisées pour chaque seuil.
Pour ignorer une option pour un seuil spécifique, utilisez un tiret bas (_
).
Par exemple, si vous ne souhaitez utiliser que deux seuils,
un pour la mesure de latence et un pour la mesure de débit,
vous voudrez probablement définir une limite supérieure pour la mesure de latence
et une limite inférieure pour la mesure de débit.
Par conséquent, vous utiliseriez --threshold-lower-boundary _
pour la mesure de latence
et --threshold-upper-boundary _
pour la mesure de débit.
Vous pourriez écrire ceci :
--threshold-measure <MEASURE>
Utilisez le nom, le slug ou l’UUID du Mesure spécifié pour un Seuil. Si la valeur spécifiée est un nom ou un slug et que le Mesure n’existe pas déjà, il sera créé pour vous. Cependant, si la valeur spécifiée est un UUID, le Mesure doit déjà exister.
Par exemple, pour utiliser un Seuil pour le Mesure de Latence,
vous pourriez écrire --threshold-measure latency
.
--threshold-test <TEST>
Utilisez le Test spécifié pour détecter les régressions de performance.
Il existe plusieurs Tests différents disponibles :
- Statique (
static
) - Pourcentage (
percentage
) - score-z (
z_score
) - test-t (
t_test
) - Log Normal (
log_normal
) - Écart Interquartile (
iqr
) - Écart Interquartile Delta (
delta_iqr
)
Par exemple, pour utiliser un Seuil avec un test t de Student,
vous pourriez écrire --threshold-test t_test
.
Statique
Un Test Statique (statique
) est le Test le plus simple.
Si une nouvelle Mesure est en dessous d’une Limite Inférieure définie ou au-dessus d’une Limite Supérieure définie, une Alerte est générée.
C’est-à-dire que la Limite Inférieure/Supérieure est une Limite Inférieure/Supérieure explicite.
Il faut définir soit une Limite Inférieure, soit une Limite Supérieure, soit les deux.
Les Tests Statiques fonctionnent mieux lorsque la valeur de la Mesure doit rester dans une plage constante pour tous les Repères,
comme la couverture de code.
-
Limite Inférieure Statique
- Une Limite Inférieure d’un Test Statique peut être n’importe quel nombre à virgule flottante. Elle est utilisée lorsqu’une valeur plus petite indiquerait une régression de performance. La Limite Inférieure doit être inférieure ou égale à la Limite Supérieure, si les deux sont spécifiées.
- Par exemple, si vous aviez un Test Statique avec une Limite Inférieure définie à
100
la Limite Inférieure serait également100
et toute valeur inférieure à100
générerait une Alerte.
-
Limite Supérieure Statique
- Une Limite Supérieure d’un Test Statique peut être n’importe quel nombre à virgule flottante. Elle est utilisée lorsqu’une valeur plus grande indiquerait une régression de performance. La Limite Supérieure doit être supérieure ou égale à la Limite Inférieure, si les deux sont spécifiées.
- Par exemple, si vous aviez un Test Statique avec une Limite Supérieure définie à
100
la Limite Supérieure serait également100
et toute valeur supérieure à100
générerait une Alerte.
Pourcentage
Un test de pourcentage (pourcentage
) est le test statistique le plus simple.
Si une nouvelle métrique est en dessous d’un certain pourcentage de la moyenne (limite inférieure)
ou au-dessus d’un certain pourcentage de la moyenne (limite supérieure) de vos métriques historiques, une alerte est générée.
Une limite inférieure, une limite supérieure, ou les deux doivent être définies.
Les tests de pourcentage fonctionnent le mieux lorsque la valeur de la métrique doit rester dans une plage connue et acceptable.
-
Limite inférieure de pourcentage
- Une limite inférieure d’un test de pourcentage peut être n’importe quel pourcentage supérieur ou égal à zéro sous forme décimale (ex: utilisez
0.10
pour10%
). Elle est utilisée lorsqu’une plus petite valeur indiquerait une régression des performances. - Par exemple, si vous avez un test de pourcentage avec une limite inférieure fixée à
0.10
et que vos métriques historiques avaient une moyenne de100
, la limite inférieure serait90
et toute valeur inférieure à90
générerait une alerte.
- Une limite inférieure d’un test de pourcentage peut être n’importe quel pourcentage supérieur ou égal à zéro sous forme décimale (ex: utilisez
-
Limite supérieure de pourcentage
- Une limite supérieure d’un test de pourcentage peut être n’importe quel pourcentage supérieur ou égal à zéro sous forme décimale (ex: utilisez
0.10
pour10%
). Elle est utilisée lorsqu’une plus grande valeur indiquerait une régression des performances. - Par exemple, si vous avez un test de pourcentage avec une limite supérieure fixée à
0.10
et que vos métriques historiques avaient une moyenne de100
, la limite supérieure serait110
et toute valeur supérieure à110
générerait une alerte.
- Une limite supérieure d’un test de pourcentage peut être n’importe quel pourcentage supérieur ou égal à zéro sous forme décimale (ex: utilisez
z-score
Un Test de z-score (z_score
) mesure le nombre d’écarts-types (σ) qu’un nouveau Métrique est par rapport à la moyenne de vos Métriques historiques en utilisant un z-score.
Les Tests de z-score fonctionnent le mieux lorsque :
- Il n’y a pas de différences extrêmes entre les exécutions de référence
- Les exécutions de référence sont totalement indépendantes les unes des autres
- Le nombre d’itérations pour une seule exécution de référence est inférieur à 10 % des Métriques historiques
- Il y a au moins 30 Métriques historiques (taille d’échantillon minimale ≥ 30)
Pour les Tests de z-score, les écarts-types sont exprimés sous forme de pourcentage cumulé décimal. Si un nouveau Métrique est en dessous d’un certain pourcentage cumulé à gauche (Limite Inférieure) ou au-dessus d’un certain pourcentage cumulé à droite (Limite Supérieure) pour vos Métriques historiques, une alerte est générée. Vous devez définir soit une Limite Inférieure, soit une Limite Supérieure, ou les deux.
-
Limite Inférieure de z-score
- Une Limite Inférieure de Test de z-score peut être n’importe quel décimal positif entre
0.5
et1.0
. Où0.5
représente la moyenne et1.0
représente toutes les valeurs possibles du côté gauche (-∞). Elle est utilisée lorsqu’une valeur plus petite indiquerait une régression de performance. - Par exemple, si vous utilisez un Test de z-score avec une Limite Inférieure de
0.977
et vos Métriques historiques avaient une moyenne de100
et un écart-type de10
, la Limite Inférieure serait80,05
et toute valeur inférieure à80,05
générerait une alerte.
- Une Limite Inférieure de Test de z-score peut être n’importe quel décimal positif entre
-
Limite Supérieure de z-score
- Une Limite Supérieure de Test de z-score peut être n’importe quel décimal positif entre
0.5
et1.0
. Où0.5
représente la moyenne et1.0
représente toutes les valeurs possibles du côté droit (∞). Elle est utilisée lorsqu’une valeur supérieure indiquerait une régression de performance. - Par exemple, si vous utilisez un Test de z-score avec une Limite Supérieure de
0.977
et vos Métriques historiques avaient une moyenne de100
et un écart-type de10
, la Limite Supérieure serait119,95
et toute valeur supérieure à119,95
générerait une alerte.
- Une Limite Supérieure de Test de z-score peut être n’importe quel décimal positif entre
t-test
Un test t (t_test
) mesure l’intervalle de confiance (CI) pour évaluer la probabilité qu’une nouvelle métrique soit au-dessus ou en-dessous de la moyenne de vos métriques historiques en utilisant un test t de Student.
Les tests t-test sont plus efficaces lorsque :
- Il n’y a pas de différences extrêmes entre les exécutions de référence
- Les exécutions de référence sont totalement indépendantes les unes des autres
- Le nombre d’itérations pour une seule exécution de référence est inférieur à 10 % des métriques historiques
Pour les tests t-test, les intervalles de confiance sont exprimés en pourcentage décimal de confiance. Si une nouvelle métrique est en dessous d’un certain pourcentage de confiance côté gauche (Limite Inférieure) ou au-dessus d’un certain pourcentage de confiance côté droit (Limite Supérieure) pour vos métriques historiques, une alerte est générée. Une limite inférieure, une limite supérieure, ou les deux doivent être définies.
-
Limite Inférieure du t-test
- La Limite Inférieure d’un test t peut être n’importe quel décimal positif entre
0.5
et1.0
. Où0.5
représente la moyenne et1.0
représente toutes les valeurs possibles du côté gauche (-∞). Elle est utilisée lorsqu’une valeur plus petite indiquerait une régression de performance. - Par exemple, si vous utilisez un test t avec une Limite Inférieure de
0.977
et que vous avez25
métriques historiques avec une moyenne de100
et un écart-type de10
, la Limite Inférieure serait78,96
et toute valeur inférieure à78,96
générerait une alerte.
- La Limite Inférieure d’un test t peut être n’importe quel décimal positif entre
-
Limite Supérieure du t-test
- La Limite Supérieure d’un test t peut être n’importe quel décimal positif entre
0.5
et1.0
. Où0.5
représente la moyenne et1.0
représente toutes les valeurs possibles du côté droit (∞). Elle est utilisée lorsqu’une valeur plus grande indiquerait une régression de performance. - Par exemple, si vous utilisez un test t avec une Limite Supérieure de
0.977
et que vous avez25
métriques historiques avec une moyenne de100
et un écart-type de10
, la Limite Supérieure serait121,04
et toute valeur supérieure à121,04
générerait une alerte.
- La Limite Supérieure d’un test t peut être n’importe quel décimal positif entre
Log Normal
Un test Log Normal (log_normal
) évalue la probabilité qu’une nouvelle métrique soit au-dessus ou en dessous du point central de vos métriques historiques en utilisant une distribution log-normale.
Les tests Log Normal fonctionnent mieux lorsque :
- Les exécutions de benchmark sont totalement indépendantes les unes des autres
- Le nombre d’itérations pour une seule exécution de benchmark est inférieur à 10 % des métriques historiques
- Toutes les données sont positives (le log naturel d’un nombre négatif est
non défini
)
Pour les tests Log Normal, la probabilité est exprimée sous forme de pourcentage décimal. Si une nouvelle métrique est en dessous d’un certain pourcentage gauche (Limite Inférieure) ou au-dessus d’un certain pourcentage droit (Limite Supérieure) de vos métriques historiques, une alerte est générée. Soit une Limite Inférieure, une Limite Supérieure, ou les deux doivent être définies.
-
Limite Inférieure Log Normale
- Une Limite Inférieure pour un test Log Normal peut être n’importe quel décimal positif entre
0,5
et1,0
. Où0,5
représente le point central et1,0
représente toutes les valeurs possibles du côté gauche (-∞). Elle est utilisée lorsqu’une valeur plus petite indiquerait une régression de performance. - Par exemple, si vous utilisez un test Log Normal avec une Limite Inférieure de
0,977
et que vous avez25
métriques historiques centrées autour de100
et un précédent écart à200
, la Limite Inférieure serait71,20
et toute valeur inférieure à71,20
générerait une alerte.
- Une Limite Inférieure pour un test Log Normal peut être n’importe quel décimal positif entre
-
Limite Supérieure Log Normale
- Une Limite Supérieure pour un test Log Normal peut être n’importe quel décimal positif entre
0,5
et1,0
. Où0,5
représente le point central et1,0
représente toutes les valeurs possibles du côté droit (∞). Elle est utilisée lorsqu’une valeur plus grande indiquerait une régression de performance. - Par exemple, si vous utilisez un test Log Normal avec une Limite Supérieure de
0,977
et que vous avez25
métriques historiques centrées autour de100
et un précédent écart à200
, la Limite Supérieure serait134,18
et toute valeur supérieure à134,18
générerait une alerte.
- Une Limite Supérieure pour un test Log Normal peut être n’importe quel décimal positif entre
Intervalle Interquartile
Un test d’intervalle interquartile (iqr
) mesure combien de multiples de l’intervalle interquartile (IQR) une nouvelle métrique se situe au-dessus ou en dessous de la médiane de vos métriques historiques. Si une nouvelle métrique est en dessous d’un certain multiple de l’IQR par rapport à la médiane (Limite Inférieure) ou au-dessus d’un certain multiple de l’IQR par rapport à la médiane (Limite Supérieure) de vos métriques historiques, une alerte est générée. Une limite inférieure, une limite supérieure ou les deux doivent être définies.
-
Limite Inférieure de l’Intervalle Interquartile
- Une limite inférieure de test d’intervalle interquartile peut être n’importe quel multiplicateur supérieur ou égal à zéro (ex : utilisez
2.0
pour2x
). Elle est utilisée lorsqu’une valeur plus petite indiquerait une régression de performance. - Par exemple, si vous avez un test d’intervalle interquartile avec une limite inférieure fixée à
2.0
et que vos métriques historiques ont une médiane de100
et un intervalle interquartile de10
, la limite inférieure serait de80
et toute valeur inférieure à80
générerait une alerte.
- Une limite inférieure de test d’intervalle interquartile peut être n’importe quel multiplicateur supérieur ou égal à zéro (ex : utilisez
-
Limite Supérieure de l’Intervalle Interquartile
- Une limite supérieure de test d’intervalle interquartile peut être n’importe quel multiplicateur supérieur ou égal à zéro (ex : utilisez
2.0
pour2x
). Elle est utilisée lorsqu’une valeur plus grande indiquerait une régression de performance. - Par exemple, si vous avez un test d’intervalle interquartile avec une limite supérieure fixée à
2.0
et que vos métriques historiques ont une médiane de100
et un intervalle interquartile de10
, la limite supérieure serait de120
et toute valeur supérieure à120
générerait une alerte.
- Une limite supérieure de test d’intervalle interquartile peut être n’importe quel multiplicateur supérieur ou égal à zéro (ex : utilisez
Delta Interquartile Range
Un test de l’Écart Interquartile Delta (delta_iqr
) mesure combien de fois l’écart interquartile (IQR) moyen du pourcentage de changement (Δ) qu’un nouveau Métrique est au-dessus ou en dessous de la médiane de vos Métriques historiques. Si un nouveau Métrique est en dessous d’un certain multiple de l’Écart Interquartile Delta par rapport à la médiane (Limite Inférieure) ou au-dessus d’un certain multiple de l’Écart Interquartile Delta par rapport à la médiane (Limite Supérieure) de vos Métriques historiques, une alerte est générée. Soit une Limite Inférieure, une Limite Supérieure, ou les deux doivent être définies.
-
Limite Inférieure de l’Écart Interquartile Delta
- Une Limite Inférieure de test de l’Écart Interquartile Delta peut être n’importe quel multiplicateur supérieur ou égal à zéro (ex : utilisez
2.0
pour2x
). Elle est utilisée lorsqu’une valeur plus petite indiquerait une régression des performances. - Par exemple, si vous aviez un test de l’Écart Interquartile Delta avec une Limite Inférieure fixée à
2.0
et que vos Métriques historiques avaient une médiane de100
, un écart interquartile de10
, et un écart interquartile delta moyen de0.2
(20%
), la Limite de la Limite Inférieure serait60
et toute valeur inférieure à60
générerait une alerte.
- Une Limite Inférieure de test de l’Écart Interquartile Delta peut être n’importe quel multiplicateur supérieur ou égal à zéro (ex : utilisez
-
Limite Supérieure de l’Écart Interquartile Delta
- Une Limite Supérieure de test de l’Écart Interquartile Delta peut être n’importe quel multiplicateur supérieur ou égal à zéro (ex : utilisez
2.0
pour2x
). Elle est utilisée lorsqu’une valeur plus grande indiquerait une régression des performances. - Par exemple, si vous aviez un test de l’Écart Interquartile Delta avec une Limite Supérieure fixée à
2.0
et que vos Métriques historiques avaient une médiane de100
, un écart interquartile de10
, et un écart interquartile delta moyen de0.2
(20%
), la Limite Supérieure serait140
et toute valeur supérieure à140
générerait une alerte.
- Une Limite Supérieure de test de l’Écart Interquartile Delta peut être n’importe quel multiplicateur supérieur ou égal à zéro (ex : utilisez
--threshold-min-per-taille-échantillon <TAILLE_ÉCHANTILLON>
Spécifiez éventuellement le nombre minimum de Métriques requis pour exécuter un Test. Si ce minimum n’est pas atteint, le Test ne s’exécutera pas. La taille de l’échantillon spécifiée doit être supérieure ou égale à 2
. Si l’option --threshold-max-sample-size
est également définie, alors la taille de l’échantillon spécifiée doit être inférieure ou égale à --threshold-max-sample-size
. Cette option ne peut pas être utilisée avec le Test Statique (static
).
Par exemple, pour utiliser un Seuil avec une taille d’échantillon minimale de 10
, vous pouvez écrire --threshold-min-sample-size 10
. S’il y avait moins de 10
Métriques, le Test ne s’exécuterait pas. Inversement, s’il y avait 10
Métriques ou plus, le Test s’exécuterait.
--threshold-max-sample-size <SAMPLE_SIZE>
Spécifiez éventuellement le nombre maximum de Métriques utilisées pour exécuter un Test. Si ce maximum est dépassé, les Métriques les plus anciennes seront ignorées. La taille d’échantillon spécifiée doit être supérieure ou égale à 2
. Si l’option --threshold-min-sample-size
est également définie, alors la taille d’échantillon spécifiée doit être supérieure ou égale à --threshold-min-sample-size
. Cette option ne peut pas être utilisée avec le Test Statique (static
).
Par exemple, pour utiliser un seuil avec une taille d’échantillon maximale de 100
, vous pourriez écrire --threshold-max-sample-size 100
. S’il y avait plus de 100
Métriques, seules les 100
Métriques les plus récentes seraient incluses. Inversement, s’il y avait 100
Métriques ou moins, toutes les Métriques seraient incluses.
--threshold-window <WINDOW>
Spécifiez éventuellement la fenêtre de temps pour les Métriques utilisées pour effectuer le Test, en secondes.
La fenêtre spécifiée doit être supérieure à 0
.
Cette option ne peut pas être utilisée avec le Test Statique (static
).
Par exemple, pour utiliser un Seuil avec une fenêtre de quatre semaines ou 2419200
secondes,
vous pourriez écrire --threshold-window 2419200
.
Si des Métriques ont plus de quatre semaines, elles seront exclues.
Inversement, si toutes les Métriques datent des quatre dernières semaines, elles seront toutes incluses.
--threshold-lower-boundary <BOUNDARY>
Spécifiez la limite inférieure. Les contraintes sur la limite inférieure dépendent du Test utilisé. Soit la limite inférieure, soit la limite supérieure, soit les deux doivent être spécifiées.
Pour plus de détails, consultez la documentation du test spécifique que vous utilisez :
- Limite inférieure statique
- Limite inférieure en pourcentage
- Limite inférieure du score z
- Limite inférieure du test t
- Limite inférieure log-normale
- Limite inférieure de l’intervalle interquartile
- Limite inférieure de la différence de l’intervalle interquartile
--threshold-upper-boundary <BOUNDARY>
Spécifiez la limite supérieure. Les contraintes sur la limite supérieure dépendent du Test utilisé. Soit la limite inférieure, la limite supérieure, soit les deux doivent être spécifiées.
Pour plus de détails, consultez la documentation du Test spécifique que vous utilisez :
- Limite Supérieure Statique
- Limite Supérieure en Pourcentage
- Limite Supérieure de Scores z
- Limite Supérieure du Test t
- Limite Supérieure Log Normale
- Limite Supérieure de l’Écart Interquartile
- Limite Supérieure de Delta de l’Écart Interquartile
---thresholds-reset
Réinitialiser tous les seuils non spécifiés pour la branche et le banc d’essai donnés. Si un seuil existe déjà et n’est pas spécifié, son modèle actuel sera supprimé.
Par exemple, s’il y avait deux seuils pour la branche main
et banc d’essai localhost
:
- Branche
main
, banc d’essailocalhost
, mesure delatence
- Branche
main
, banc d’essailocalhost
, mesure dedébit
Si seule la mesure de latence
est spécifiée dans la sous-commande bencher run
et --thresholds-reset
est utilisé,
alors la mesure de débit
aurait son modèle supprimé.
--err
Optionnellement, génère une erreur lorsqu’une Alerte est déclenchée. Une Alerte est générée lorsqu’une nouvelle Métrique est en dessous d’une Limite Inférieure ou au-dessus d’une Limite Supérieure.
Suppression des Alertes
Parfois, il peut être utile de supprimer les Alertes pour un Benchmark particulier. La meilleure façon de le faire est d’ajouter un de ces suffixes spéciaux au nom de ce Benchmark :
_bencher_ignore
BencherIgnore
-bencher-ignore
Par exemple, si votre Benchmark s’appelait my_flaky_benchmark
, le renommer en my_flaky_benchmark_bencher_ignore
permettrait d’ignorer juste ce Benchmark particulier à l’avenir.
Les Benchmarks ignorés sont tout de même vérifiés par rapport aux Seuils existants.
Cependant, une Alerte ne sera pas générée pour eux.
Les Métriques pour les Benchmarks ignorés sont toujours stockées.
Les résultats de my_flaky_benchmark_bencher_ignore
seraient toujours stockés sous le Benchmark my_flaky_benchmark
.
Si vous retirez le suffixe et revenez au nom original du Benchmark,
alors les choses reprendront là où vous vous étiez arrêté.
🐰 Bravo! Vous avez tout appris sur les Seuils & Alertes! 🎉