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 :

bencher run \
--project project-abc4567-wxyz123456789 \
--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

🐰 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 :

bencher run \
--project project-abc4567-wxyz123456789 \
--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>

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 :

• Pourcentage (percentage)
• score-z (z_score)
• test-t (t_test)
• Log Normal (log_normal)
• Écart Interquartile (iqr)
• Écart Interquartile Delta (delta_iqr)
• Statique (static)

Par exemple, pour utiliser un Seuil avec un test t de Student, vous pourriez écrire --threshold-test t_test.

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 pour 10%). 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 de 100, la limite inférieure serait 90 et toute valeur inférieure à 90 générerait une alerte.

• 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 pour 10%). 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 de 100, la limite supérieure serait 110 et toute valeur supérieure à 110 générerait une alerte.

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 et 1.0. Où 0.5 représente la moyenne et 1.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 de 100 et un écart-type de 10, la Limite Inférieure serait 80,05 et toute valeur inférieure à 80,05 générerait une alerte.

• 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 et 1.0. Où 0.5 représente la moyenne et 1.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 de 100 et un écart-type de 10, la Limite Supérieure serait 119,95 et toute valeur supérieure à 119,95 générerait une alerte.

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 et 1.0. Où 0.5 représente la moyenne et 1.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 avez 25 métriques historiques avec une moyenne de 100 et un écart-type de 10, la Limite Inférieure serait 78,96 et toute valeur inférieure à 78,96 générerait une alerte.

• 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 et 1.0. Où 0.5 représente la moyenne et 1.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 avez 25 métriques historiques avec une moyenne de 100 et un écart-type de 10, la Limite Supérieure serait 121,04 et toute valeur supérieure à 121,04 générerait une alerte.

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 et 1,0. Où 0,5 représente le point central et 1,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 avez 25 métriques historiques centrées autour de 100 et un précédent écart à 200, la Limite Inférieure serait 71,20 et toute valeur inférieure à 71,20 générerait une alerte.

• 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 et 1,0. Où 0,5 représente le point central et 1,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 avez 25 métriques historiques centrées autour de 100 et un précédent écart à 200, la Limite Supérieure serait 134,18 et toute valeur supérieure à 134,18 générerait une alerte.

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 pour 2x). 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 de 100 et un intervalle interquartile de 10, la limite inférieure serait de 80 et toute valeur inférieure à 80 générerait une alerte.

• 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 pour 2x). 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 de 100 et un intervalle interquartile de 10, la limite supérieure serait de 120 et toute valeur supérieure à 120 générerait une alerte.

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 pour 2x). 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 de 100, un écart interquartile de 10, et un écart interquartile delta moyen de 0.2 (20%), la Limite de la Limite Inférieure serait 60 et toute valeur inférieure à 60 générerait une alerte.

• 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 pour 2x). 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 de 100, un écart interquartile de 10, et un écart interquartile delta moyen de 0.2 (20%), la Limite Supérieure serait 140 et toute valeur supérieure à 140 générerait une alerte.

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.

🐰 Si vous souhaitez une limite de seuil inférieure/supérieure statique différente pour chaque benchmark, alors vous devriez utiliser le Test de Pourcentage (percentage) avec la Limite Inférieure/Supérieure définie à 0.0 et la Taille d’Échantillon Max définie à 2.

• 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 également 100 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 également 100 et toute valeur supérieure à 100 générerait une Alerte.

--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 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
• Limite inférieure statique

--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 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
• Limite Supérieure Statique

---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’essai localhost, mesure de latence
• Branche main, banc d’essai localhost, mesure de dé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! 🎉

Continuez : Adaptateurs de banc d’essai ➡