Umbrales & Alertas

Los Umbrales son cómo detectas regresiones de rendimiento con Bencher. Un Umbral se asigna a una combinación única de: Branch, Testbed y Measure. Un Umbral utiliza un Test específico para detectar regresiones de rendimiento. La combinación de un Test y sus parámetros se llama Modelo. Un Modelo debe tener un Límite Inferior, un Límite Superior, o ambos.

• Límite Inferior
  • Se utiliza un Límite Inferior cuando un valor más pequeño indicaría una regresión de rendimiento, como con la Medida de Rendimiento.
• Límite Superior
  • Se utiliza un Límite Superior cuando un valor más grande indicaría una regresión de rendimiento, como con la Medida de Latencia.

Cada Límite se utiliza para calcular un Límite de Umbral. Luego, cada nuevo Metric se verifica contra cada Límite de Umbral. Se genera una alerta cuando un nuevo Métrico está por debajo del Límite Inferior o por encima del Límite Superior.

Al realizar [Benchmarking Continuo], es decir, benchmarking en CI, querrás crear Umbrales. Usando el subcomando bencher run de la CLI, ya especificas una Rama con la opción --branch y un Banco de Pruebas con la opción --testbed. Así que la única otra dimensión que necesitas especificar es una Medida, con la opción --threshold-measure. Luego puedes usar la opción --threshold-test para especificar el Test a usar para esa Medida. Las opciones --threshold-min-sample-size, --threshold-max-sample-size y --threshold-window te permiten controlar qué datos se utilizan por el Test. Finalmente, las opciones --threshold-lower-boundary y --threshold-upper-boundary te permiten establecer el Límite Inferior y el Límite Superior. Si deseas eliminar todos los Modelos que no estén especificados, puedes hacerlo con el flag --thresholds-reset.

• Si el Umbral no existe, se creará para ti.
• Si el Umbral existe y el Modelo especificado es el mismo, entonces el Modelo se ignora.
• Si el Umbral existe y el Modelo especificado es diferente, entonces se crea un nuevo Modelo para el Umbral.
• Si un Umbral existe y se restablece, entonces el Modelo actual se elimina del Umbral.

Por ejemplo, para usar solo un Umbral para la Medida de Latencia utilizando una Prueba t de Student con un tamaño de muestra máximo de 64 y un Límite Superior de 0.99, podrías escribir algo así:

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

🐰 Al trabajar con ramas de características, es posible que desees copiar los Umbrales existentes desde la rama base, Punto de Inicio. Esto es posible con el flag --start-point-clone-thresholds. Ten en cuenta que el flag --thresholds-reset aún eliminará cualquier Umbral clonado que no se especifique explícitamente.

Múltiples Umbrales

Es posible crear múltiples Umbrales con la misma invocación de bencher run. Al especificar múltiples Umbrales, se deben utilizar las mismas opciones para cada Umbral. Para ignorar una opción para un Umbral específico, utiliza un guion bajo (_).

Por ejemplo, si solo deseas utilizar dos Umbrales, uno para la Medida de Latencia y otro para la Medida de Rendimiento, entonces probablemente querrás establecer un Límite Superior para la Medida de Latencia y un Límite Inferior para la Medida de Rendimiento. Por lo tanto, utilizarías --threshold-lower-boundary _ para la Medida de Latencia y --threshold-upper-boundary _ para la Medida de Rendimiento. Podrías escribir algo así:

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>

Utilice el nombre del Measure especificado, slug o UUID para un Umbral. Si el valor especificado es un nombre o slug y el Measure no existe ya, se creará para usted. Sin embargo, si el valor especificado es un UUID, entonces el Measure ya debe existir.

Por ejemplo, para usar un Umbral para el Measure de Latencia, podría escribir --threshold-measure latency.

--threshold-test <TEST>

Utilice la prueba especificada para detectar regresiones de rendimiento.

Hay varias pruebas diferentes disponibles:

• Percentage (percentage)
• z-score (z_score)
• t-test (t_test)
• Log Normal (log_normal)
• Interquartile Range (iqr)
• Delta Interquartile Range (delta_iqr)
• Static (static)

Por ejemplo, para utilizar un umbral con una prueba t de Student, podría escribir --threshold-test t_test.

Porcentaje

Una Prueba de Porcentaje (percentage) es la Prueba estadística más simple. Si una nueva Métrica está por debajo de un cierto porcentaje de la media (Límite Inferior) o por encima de un cierto porcentaje de la media (Límite Superior) de tus Métricas históricas, se genera una Alerta. Se debe establecer un Límite Inferior, un Límite Superior o ambos. Las Pruebas de Porcentaje funcionan mejor cuando el valor de la Métrica debería mantenerse dentro de un rango reconocido como bueno.

• Límite Inferior de Porcentaje

  • Un Límite Inferior de una Prueba de Porcentaje puede ser cualquier porcentaje mayor o igual a cero en forma decimal (ej: usa 0.10 para 10%). Se utiliza cuando un valor menor indicaría una regresión en el rendimiento.
  • Por ejemplo, si tienes una Prueba de Porcentaje con un Límite Inferior establecido en 0.10 y tus Métricas históricas tienen una media de 100, el Límite Inferior sería 90 y cualquier valor menor que 90 generaría una Alerta.

• Límite Superior de Porcentaje

  • Un Límite Superior de una Prueba de Porcentaje puede ser cualquier porcentaje mayor o igual a cero en forma decimal (ej: usa 0.10 para 10%). Se utiliza cuando un valor mayor indicaría una regresión en el rendimiento.
  • Por ejemplo, si tienes una Prueba de Porcentaje con un Límite Superior establecido en 0.10 y tus Métricas históricas tienen una media de 100, el Límite Superior sería 110 y cualquier valor mayor que 110 generaría una Alerta.

z-score

Una Prueba de puntuación z (z_score) mide el número de desviaciones estándar (σ) que un nuevo Métrico tiene respecto a la media de sus Métricos históricos usando una puntuación z.

Las Pruebas de puntuación z funcionan mejor cuando:

• No hay diferencias extremas entre ejecuciones de referencia
• Las ejecuciones de referencia son totalmente independientes entre sí
• El número de iteraciones para una sola ejecución de referencia es menos del 10% de los Métricos históricos
• Hay al menos 30 Métricos históricos (Tamaño de Muestra mínimo >= 30)

Para las Pruebas de puntuación z, las desviaciones estándar se expresan como un porcentaje acumulativo decimal. Si un nuevo Métrico está por debajo de cierto porcentaje acumulativo del lado izquierdo (Límite Inferior) o por encima de cierto porcentaje acumulativo del lado derecho (Límite Superior) de sus Métricos históricos, se genera una Alerta. Debe establecerse un Límite Inferior, un Límite Superior, o ambos.

• Límite Inferior de puntuación z

  • Un Límite Inferior de una Prueba de puntuación z puede ser cualquier decimal positivo entre 0.5 y 1.0. Donde 0.5 representa la media y 1.0 representa todos los posibles valores del lado izquierdo (-∞). Se utiliza cuando un valor más pequeño indicaría una regresión de rendimiento.
  • Por ejemplo, si utiliza una Prueba de puntuación z con un Límite Inferior de 0.977 y sus Métricos históricos tenían una media de 100 y una desviación estándar de 10, el Límite Inferior sería 80.05 y cualquier valor menor que 80.05 generaría una Alerta.

• Límite Superior de puntuación z

  • Un Límite Superior de una Prueba de puntuación z puede ser cualquier decimal positivo entre 0.5 y 1.0. Donde 0.5 representa la media y 1.0 representa todos los posibles valores del lado derecho (∞). Se utiliza cuando un valor mayor indicaría una regresión de rendimiento.
  • Por ejemplo, si utiliza una Prueba de puntuación z con un Límite Superior de 0.977 y sus Métricos históricos tenían una media de 100 y una desviación estándar de 10, el Límite Superior sería 119.95 y cualquier valor mayor que 119.95 generaría una Alerta.

t-test

Una prueba t (t_test) mide el intervalo de confianza (IC) para determinar la probabilidad de que una nueva Métrica esté por encima o por debajo de la media de tus Métricas históricas usando una prueba t de Student.

Las pruebas t funcionan mejor cuando:

• No hay diferencias extremas entre ejecuciones de referencia
• Las ejecuciones de referencia son totalmente independientes entre sí
• El número de iteraciones para una sola ejecución de referencia es menos del 10% de las Métricas históricas

Para las pruebas t, los intervalos de confianza se expresan como un porcentaje de confianza decimal. Si una nueva Métrica está por debajo de un cierto porcentaje de confianza del lado izquierdo (Límite Inferior) o por encima de un cierto porcentaje de confianza del lado derecho (Límite Superior) para tus Métricas históricas, se genera una Alerta. Se debe establecer un Límite Inferior, un Límite Superior, o ambos.

• Límite Inferior de la prueba t

  • Un Límite Inferior de la prueba t puede ser cualquier número decimal positivo entre 0.5 y 1.0. Donde 0.5 representa la media y 1.0 representa todos los posibles valores del lado izquierdo (-∞). Se utiliza cuando un valor más pequeño indicaría una regresión de rendimiento.
  • Por ejemplo, si utilizas una prueba t con un Límite Inferior de 0.977 y tienes 25 Métricas históricas con una media de 100 y una desviación estándar de 10, el Límite Inferior sería 78.96 y cualquier valor menor que 78.96 generaría una Alerta.

• Límite Superior de la prueba t

  • Un Límite Superior de la prueba t puede ser cualquier número decimal positivo entre 0.5 y 1.0. Donde 0.5 representa la media y 1.0 representa todos los posibles valores del lado derecho (∞). Se utiliza cuando un valor mayor indicaría una regresión de rendimiento.
  • Por ejemplo, si utilizas una prueba t con un Límite Superior de 0.977 y tienes 25 Métricas históricas con una media de 100 y una desviación estándar de 10, el Límite Superior sería 121.04 y cualquier valor mayor que 121.04 generaría una Alerta.

Log Normal

Una Prueba de Log Normal (log_normal) mide qué tan probable es que una nueva Métrica esté por encima o por debajo de la ubicación central de tus Métricas históricas utilizando una Distribución Log Normal.

Las Pruebas de Log Normal funcionan mejor cuando:

• Las ejecuciones de referencia son totalmente independientes entre sí
• El número de iteraciones para una sola ejecución de referencia es menos del 10% de las Métricas históricas
• Todos los datos son positivos (el logaritmo natural de un número negativo es indefinido)

Para las Pruebas de Log Normal, la probabilidad se expresa como un porcentaje decimal. Si una nueva Métrica está por debajo de cierto porcentaje del lado izquierdo (Límite Inferior) o por encima de cierto porcentaje del lado derecho (Límite Superior) para tus Métricas históricas, se genera una Alerta. Se debe establecer ya sea un Límite Inferior, un Límite Superior, o ambos.

• Límite Inferior del Log Normal

  • Un Límite Inferior de una Prueba de Log Normal puede ser cualquier decimal positivo entre 0.5 y 1.0. Donde 0.5 representa la ubicación central y 1.0 representa todos los posibles valores del lado izquierdo (-∞). Se utiliza cuando un valor menor indicaría una regresión de rendimiento.
  • Por ejemplo, si utilizas una Prueba de Log Normal con un Límite Inferior de 0.977 y tienes 25 Métricas históricas centradas alrededor de 100 y un anterior valor atípico en 200, el Límite Inferior sería 71.20 y cualquier valor menor que 71.20 generaría una Alerta.

• Límite Superior del Log Normal

  • Un Límite Superior de una Prueba de Log Normal puede ser cualquier decimal positivo entre 0.5 y 1.0. Donde 0.5 representa la ubicación central y 1.0 representa todos los posibles valores del lado derecho (∞). Se utiliza cuando un valor mayor indicaría una regresión de rendimiento.
  • Por ejemplo, si utilizas una Prueba de Log Normal con un Límite Superior de 0.977 y tienes 25 Métricas históricas centradas alrededor de 100 y un anterior valor atípico en 200, el Límite Superior sería 134.18 y cualquier valor mayor que 134.18 generaría una Alerta.

Rango Intercuartílico

Una Prueba de Rango Intercuartílico (iqr) mide cuántos múltiplos del rango intercuartílico (IQR) está una nueva Métrica por encima o por debajo de la mediana de tus Métricas históricas. Si una nueva Métrica está por debajo de cierto múltiplo del IQR desde la mediana (Límite Inferior) o por encima de cierto múltiplo del IQR desde la mediana (Límite Superior) de tus Métricas históricas, se genera una Alerta. Se debe establecer ya sea un Límite Inferior, un Límite Superior, o ambos.

• Límite Inferior del Rango Intercuartílico

  • Un Límite Inferior de Prueba de Rango Intercuartílico puede ser cualquier multiplicador mayor o igual a cero (ej: usar 2.0 para 2x). Se utiliza cuando un valor menor indicaría una regresión en el rendimiento.
  • Por ejemplo, si tuvieras una Prueba de Rango Intercuartílico con un Límite Inferior establecido en 2.0 y tus Métricas históricas tuviesen una mediana de 100 y un rango intercuartílico de 10, el Límite Inferior sería 80 y cualquier valor menor que 80 generaría una Alerta.

• Límite Superior del Rango Intercuartílico

  • Un Límite Superior de Prueba de Rango Intercuartílico puede ser cualquier multiplicador mayor o igual a cero (ej: usar 2.0 para 2x). Se utiliza cuando un valor mayor indicaría una regresión en el rendimiento.
  • Por ejemplo, si tuvieras una Prueba de Rango Intercuartílico con un Límite Superior establecido en 2.0 y tus Métricas históricas tuviesen una mediana de 100 y un rango intercuartílico de 10, el Límite Superior sería 120 y cualquier valor mayor que 120 generaría una Alerta.

Rango intercuartil Delta

Una prueba de Rango Intercuartil Delta (delta_iqr) mide cuántos múltiplos del promedio de cambio porcentual (Δ) del rango intercuartil (IQR) un nuevo Métrico está por encima o por debajo de la mediana de tus Métricas históricas. Si un nuevo Métrico está por debajo de un cierto múltiplo del ΔIQR de la mediana (Límite Inferior) o por encima de un cierto múltiplo del ΔIQR de la mediana (Límite Superior) de tus Métricas históricas, se genera una Alerta. Debe establecerse al menos un Límite Inferior, un Límite Superior o ambos.

• Límite Inferior del Rango Intercuartil Delta

  • Un Límite Inferior de la Prueba de Rango Intercuartil Delta puede ser cualquier multiplicador mayor o igual a cero (ej: usa 2.0 para 2x). Se utiliza cuando un valor menor indicaría una regresión en el rendimiento.
  • Por ejemplo, si tuvieras una Prueba de Rango Intercuartil Delta con un Límite Inferior establecido en 2.0 y tus Métricas históricas tuvieran una mediana de 100, un rango intercuartil de 10, y un rango intercuartil delta promedio de 0.2 (20%) el Límite Inferior sería 60 y cualquier valor menor a 60 generaría una Alerta.

• Límite Superior del Rango Intercuartil Delta

  • Un Límite Superior de la Prueba de Rango Intercuartil Delta puede ser cualquier multiplicador mayor o igual a cero (ej: usa 2.0 para 2x). Se utiliza cuando un valor mayor indicaría una regresión en el rendimiento.
  • Por ejemplo, si tuvieras una Prueba de Rango Intercuartil Delta con un Límite Superior establecido en 2.0 y tus Métricas históricas tuvieran una mediana de 100, un rango intercuartil de 10, y un rango intercuartil delta promedio de 0.2 (20%) el Límite Superior sería 140 y cualquier valor mayor a 140 generaría una Alerta.

Static

Una Prueba Estática (static) es la prueba más sencilla. Si un nueva Métrica está por debajo de un Límite Inferior establecido o por encima de un Límite Superior establecido, se genera una Alerta. Es decir, el Límite Inferior/Superior es un Límite Inferior/Superior explícito. Debe establecerse un Límite Inferior, un Límite Superior, o ambos. Las Pruebas Estáticas funcionan mejor cuando el valor de la Métrica debe mantenerse dentro de un rango constante en todos los Benchmarks, como la cobertura de código.

🐰 Si deseas un Límite Inferior/Superior Estático diferente para cada Benchmark, entonces deberías usar Prueba de Porcentaje (percentage) con el Límite Inferior/Superior establecido en 0.0 y el Tamaño Máximo de Muestra establecido en 2.

• Límite Inferior Estático

• Un Límite Inferior de Prueba Estática puede ser cualquier número de punto flotante. Se utiliza cuando un valor más pequeño indicaría una regresión de rendimiento. El Límite Inferior debe ser menor o igual al Límite Superior, si ambos están especificados.
• Por ejemplo, si tuvieras una Prueba Estática con un Límite Inferior establecido en 100, el Límite Inferior sería igualmente 100 y cualquier valor menor a 100 generaría una Alerta.

• Límite Superior Estático

• Un Límite Superior de Prueba Estática puede ser cualquier número de punto flotante. Se utiliza cuando un valor mayor indicaría una regresión de rendimiento. El Límite Superior debe ser mayor o igual al Límite Inferior, si ambos están especificados.
• Por ejemplo, si tuvieras una Prueba Estática con un Límite Superior establecido en 100, el Límite Superior sería igualmente 100 y cualquier valor mayor a 100 generaría una Alerta.

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

Opcionalmente, especifique el número mínimo de Métricas requerido para ejecutar una Prueba. Si no se cumple este mínimo, la Prueba no se ejecutará. El tamaño de muestra especificado debe ser mayor o igual a 2. Si también se establece la opción --threshold-max-sample-size, entonces el tamaño de muestra especificado debe ser menor o igual a --threshold-max-sample-size. Esta opción no se puede utilizar con la Prueba Estática (static)static.

Por ejemplo, para usar un Umbral con un tamaño de muestra mínimo de 10, podría escribir --threshold-min-sample-size 10. Si hubiera menos de 10 Métricas, la Prueba no se ejecutaría. Por el contrario, si hubiera 10 o más Métricas, la Prueba se ejecutaría.

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

Opcionalmente, especifique el número máximo de Métricas utilizadas para ejecutar una Prueba. Si este máximo se excede, se ignorarán las Métricas más antiguas. El tamaño de muestra especificado debe ser mayor o igual a 2. Si también se establece la opción --threshold-min-sample-size, entonces el tamaño de muestra especificado debe ser mayor o igual a --threshold-min-sample-size. Esta opción no se puede usar con la Prueba Estática (static).

Por ejemplo, para usar un Umbral con un tamaño de muestra máximo de 100, podría escribir --threshold-max-sample-size 100. Si hubiera más de 100 Métricas, solo se incluirían las 100 Métricas más recientes. Por el contrario, si hubiera 100 o menos Métricas, todas las Métricas serían incluidas.

--threshold-window <WINDOW>

Opcionalmente, especifica el intervalo de tiempo para las Métricas utilizadas para realizar la Prueba, en segundos. La ventana especificada debe ser mayor a 0. Esta opción no se puede utilizar con la Prueba Estática (static).

Por ejemplo, para usar un Umbral con una ventana de cuatro semanas o 2419200 segundos, podrías escribir --threshold-window 2419200. Si hay alguna Métrica más antigua de cuatro semanas, sería excluida. Por el contrario, si todas las Métricas son de las últimas cuatro semanas, todas serían incluidas.

--threshold-lower-boundary <BOUNDARY>

Especifica el Límite Inferior. Las restricciones para el Límite Inferior dependen de la Prueba utilizada. Se debe especificar el Límite Inferior, el Límite Superior o ambos.

Para más detalles, consulte la documentación de la prueba específica que está utilizando:

• Límite Inferior Porcentual
• Límite Inferior z-score
• Límite Inferior t-test
• Límite Inferior Log Normal
• Límite Inferior del Rango Intercuartílico
• Límite Inferior del Delta del Rango Intercuartílico
• Límite Inferior Estático

--threshold-upper-boundary <BOUNDARY>

Especifica el Límite Superior. Las restricciones sobre el Límite Superior dependen de la Prueba utilizada. Deben especificarse o el Límite Inferior, el Límite Superior, o ambos.

Para más detalles, consulta la documentación de la Prueba específica que estás utilizando:

• Límite Superior de Porcentaje
• Límite Superior de puntuación z
• Límite Superior de prueba t
• Límite Superior Log Normal
• Límite Superior del Rango Intercuartílico
• Límite Superior Delta del Rango Intercuartílico
• Límite Superior Estático

---thresholds-reset

Restablecer todos los Umbrales no especificados para el Branch y Testbed dados. Si ya existe un Umbral y no está especificado, su Modelo actual será eliminado.

Por ejemplo, si había dos Umbrales para el Branch main y Testbed localhost:

• Branch main, Testbed localhost, Medida latency
• Branch main, Testbed localhost, Medida throughput

Si solo se especifica la Medida latency en el subcomando bencher run y se utiliza --thresholds-reset, entonces la Medida throughput tendría su Modelo eliminado.

--err

Opcionalmente, error cuando se genera una Alerta. Se genera una Alerta cuando un nuevo Métrica está por debajo de un Límite Inferior o por encima de un Límite Superior.

Supresión de Alertas

A veces puede ser útil suprimir Alertas para un Benchmark en particular. La mejor manera de hacer esto es agregando uno de estos sufijos especiales al nombre de ese Benchmark:

• _bencher_ignore
• BencherIgnore
• -bencher-ignore

Por ejemplo, si su Benchmark se llamaba my_flaky_benchmark, al renombrarlo a my_flaky_benchmark_bencher_ignore se ignorará solo ese Benchmark en particular en el futuro. Los Benchmarks ignorados sí se verifican contra los Umbrales existentes. Sin embargo, no se generará una Alerta para ellos. Las Métricas de los Benchmarks ignorados siguen siendo almacenadas. Los resultados de my_flaky_benchmark_bencher_ignore aún se almacenarían como el Benchmark my_flaky_benchmark. Si elimina el sufijo y vuelve al nombre original del Benchmark, las cosas continuarán justo donde las dejó.

🐰 ¡Felicidades! ¡Has aprendido todo sobre Umbrales & Alertas! 🎉

Continúa: Adaptadores de Harness de Benchmark ➡