Limites & Alertas

Limiares são como você detecta regressões de desempenho com o Bencher. Um Limiar é atribuído a uma combinação única de: Ramo, bancada de testes e medida. Um Limiar usa um teste específico para detectar regressões de desempenho. A combinação de um teste e seus parâmetros é chamada de Modelo. Um Modelo deve ter um Limite Inferior, Superior, ou ambos.

• Limite Inferior
  • Um Limite Inferior é usado quando um valor menor indicaria uma regressão de desempenho, como na Medida de Vazão.
• Limite Superior
  • Um Limite Superior é usado quando um valor maior indicaria uma regressão de desempenho, como na Medida de Latência.

Cada Limite é usado para calcular um Limite de Fronteira. Então, cada novo métrica é verificada em relação a cada Limite de Fronteira. Um alerta é gerado quando uma nova Métrica está abaixo de um Limite Inferior de Fronteira ou acima de um Limite Superior de Fronteira.

Quando [Benchmarking Contínuo], ou seja, benchmarking em CI, você vai querer criar Limiares. Usando o subcomando de CLI bencher run, você já especifica um Ramo com a opção --branch e uma bancada de testes com a opção --testbed. Assim, a única outra dimensão que você precisa especificar é uma Medida, com a opção --threshold-measure. Então, você pode usar a opção --threshold-test para especificar o Teste a ser usado para essa Medida. As opções --threshold-min-sample-size, --threshold-max-sample-size e --threshold-window permitem controlar quais dados são usados pelo Teste. Finalmente, as opções --threshold-lower-boundary e --threshold-upper-boundary permitem que você defina o Limite Inferior e o Limite Superior. Se você quiser remover todos os Modelos não especificados, pode fazer isso com a flag --thresholds-reset.

• Se o Limiar não existir, ele será criado para você.
• Se o Limiar existir e o Modelo especificado for o mesmo, então o Modelo é ignorado.
• Se o Limiar existir e o Modelo especificado for diferente, então um novo Modelo é criado para o Limiar.
• Se um Limiar existir e for redefinido, então o Modelo atual é removido do Limiar.

Por exemplo, para usar apenas um Limiar para a Medida de Latência usando um Teste t de Student com um tamanho máximo de amostra de 64 e um Limite Superior de 0.99, você poderia escrever algo assim:

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

🐰 Quando estiver trabalhando com branches de recursos, você pode querer copiar os Limiares existentes do Ramo base, Ponto de Partida. Isso é possível com a flag --start-point-clone-thresholds. Note que a flag --thresholds-reset ainda removerá quaisquer Limiares clonados que não sejam explicitamente especificados.

Múltiplos Limiares

É possível criar múltiplos Limiares com a mesma invocação bencher run. Ao especificar múltiplos Limiares, todas as mesmas opções devem ser usadas para cada Limiar. Para ignorar uma opção para um Limiar específico, use um sublinhado (_).

Por exemplo, se você deseja usar apenas dois Limiares, um para a Medida de Latência e outro para a Medida de Vazão, provavelmente desejará definir um Limite Superior para a Medida de Latência e um Limite Inferior para a Medida de Vazão. Portanto, você utilizaria --threshold-lower-boundary _ para a Medida de Latência e --threshold-upper-boundary _ para a Medida de Vazão. Você poderia escrever algo assim:

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>

Use o nome, slug ou UUID do Measure especificado para um Threshold. Se o valor especificado for um nome ou slug e o Measure não existir, ele será criado para você. No entanto, se o valor especificado for um UUID, então o Measure já deve existir.

Por exemplo, para usar um Threshold para o Measure de Latência, você pode escrever --threshold-measure latency.

--threshold-test <TEST>

Use o Teste especificado para detectar regressões de desempenho.

Existem vários Testes diferentes disponíveis:

• Porcentagem (percentage)
• z-score (z_score)
• t-test (t_test)
• Log Normal (log_normal)
• Intervalo Interquartil (iqr)
• Delta Intervalo Interquartil (delta_iqr)
• Estático (static)

Por exemplo, para usar um Limite com um teste t de Student, você poderia escrever --threshold-test t_test.

Porcentagem

Um Teste de Porcentagem (percentage) é o Teste estatístico mais simples. Se uma nova Métrica estiver abaixo de uma certa porcentagem da média (Limite Inferior) ou acima de uma certa porcentagem da média (Limite Superior) de suas Métricas históricas, um Alerta é gerado. Deve-se definir um Limite Inferior, Limite Superior ou ambos. Testes de Porcentagem funcionam melhor quando o valor da Métrica deve permanecer dentro de um intervalo considerado bom.

• Limite Inferior de Porcentagem

  • Um Limite Inferior de Teste de Porcentagem pode ser qualquer porcentagem maior ou igual a zero em forma decimal (ex: use 0.10 para 10%). É utilizado quando um valor menor indicaria uma regressão de desempenho.
  • Por exemplo, se você tivesse um Teste de Porcentagem com um Limite Inferior definido em 0.10 e suas Métricas históricas tivessem uma média de 100, o Limite Inferior seria 90 e qualquer valor inferior a 90 geraria um Alerta.

• Limite Superior de Porcentagem

  • Um Limite Superior de Teste de Porcentagem pode ser qualquer porcentagem maior ou igual a zero em forma decimal (ex: use 0.10 para 10%). É utilizado quando um valor maior indicaria uma regressão de desempenho.
  • Por exemplo, se você tivesse um Teste de Porcentagem com um Limite Superior definido em 0.10 e suas Métricas históricas tivessem uma média de 100, o Limite Superior seria 110 e qualquer valor maior que 110 geraria um Alerta.

z-score

Um Teste de z-score (z_score) mede o número de desvios padrão (σ) que uma nova Métrica está em relação à média de suas Métricas históricas usando um z-score.

Testes de z-score funcionam melhor quando:

• Não existem diferenças extremas entre execuções de benchmark
• Execuções de benchmark são totalmente independentes umas das outras
• O número de iterações para uma única execução de benchmark é inferior a 10% das Métricas históricas
• Há pelo menos 30 Métricas históricas (Tamanho mínimo da amostra >= 30)

Para Testes de z-score, desvios padrão são expressos como uma porcentagem cumulativa decimal. Se uma nova Métrica estiver abaixo de uma certa porcentagem cumulativa do lado esquerdo (Limite Inferior) ou acima de uma certa porcentagem cumulativa do lado direito (Limite Superior) para suas Métricas históricas, um Alerta é gerado. Deve-se definir pelo menos um Limite Inferior, Limite Superior ou ambos.

• Limite Inferior do z-score

  • Um Limite Inferior de Teste de z-score pode ser qualquer decimal positivo entre 0.5 e 1.0. Onde 0.5 representa a média e 1.0 representa todos os possíveis valores do lado esquerdo (-∞). É usado quando um valor menor indicaria uma regressão de desempenho.
  • Por exemplo, se você usasse um Teste de z-score com um Limite Inferior de 0.977 e suas Métricas históricas tivessem uma média de 100 e um desvio padrão de 10, o Limite Inferior seria 80.05 e qualquer valor inferior a 80.05 geraria um Alerta.

• Limite Superior do z-score

  • Um Limite Superior de Teste de z-score pode ser qualquer decimal positivo entre 0.5 e 1.0. Onde 0.5 representa a média e 1.0 representa todos os possíveis valores do lado direito (∞). É usado quando um valor maior indicaria uma regressão de desempenho.
  • Por exemplo, se você usasse um Teste de z-score com um Limite Superior de 0.977 e suas Métricas históricas tivessem uma média de 100 e um desvio padrão de 10, o Limite Superior seria 119.95 e qualquer valor superior a 119.95 geraria um Alerta.

t-test

Um Teste t (t_test) mede o intervalo de confiança (IC) para a probabilidade de que uma nova Métrica esteja acima ou abaixo da média das suas Métricas históricas usando um teste t de Student.

Testes t-test funcionam melhor quando:

• Não há diferenças extremas entre as execuções de benchmark
• As execuções de benchmark são totalmente independentes umas das outras
• O número de iterações para uma única execução de benchmark é inferior a 10% das Métricas históricas

Para Testes t-test, os intervalos de confiança são expressos como uma porcentagem decimal de confiança. Se uma nova Métrica estiver abaixo de uma certa porcentagem de confiança do lado esquerdo (Limite Inferior) ou acima de uma certa porcentagem de confiança do lado direito (Limite Superior) para suas Métricas históricas, será gerado um Alerta. Deve-se definir ou um Limite Inferior, um Limite Superior, ou ambos.

• Limite Inferior do t-test

  • Um Limite Inferior do Teste t-test pode ser qualquer decimal positivo entre 0.5 e 1.0. Onde 0.5 representa a média e 1.0 representa todos os possíveis valores do lado esquerdo (-∞). É utilizado quando um valor menor indicaria uma regressão de desempenho.
  • Por exemplo, se você usou um Teste t-test com um Limite Inferior de 0.977 e tinha 25 Métricas históricas com uma média de 100 e um desvio padrão de 10, o Limite Inferior seria 78.96 e qualquer valor inferior a 78.96 geraria um Alerta.

• Limite Superior do t-test

  • Um Limite Superior do Teste t-test pode ser qualquer decimal positivo entre 0.5 e 1.0. Onde 0.5 representa a média e 1.0 representa todos os possíveis valores do lado direito (∞). É utilizado quando um valor maior indicaria uma regressão de desempenho.
  • Por exemplo, se você usou um Teste t-test com um Limite Superior de 0.977 e tinha 25 Métricas históricas com uma média de 100 e um desvio padrão de 10, o Limite Superior seria 121.04 e qualquer valor superior a 121.04 geraria um Alerta.

Log Normal

Um Teste Log Normal (log_normal) mede a probabilidade de uma nova Métrica estar acima ou abaixo da localização central de suas Métricas históricas usando uma Distribuição Log Normal.

Os Testes Log Normal funcionam melhor quando:

• As execuções dos benchmarks são totalmente independentes umas das outras
• O número de iterações de uma única execução de benchmark é menor que 10% das Métricas históricas
• Todos os dados são positivos (o logaritmo natural de um número negativo é indefinido)

Para Testes Log Normal, a probabilidade é expressa como uma porcentagem decimal. Se uma nova Métrica estiver abaixo de uma certa porcentagem do lado esquerdo (Limite Inferior) ou acima de uma certa porcentagem do lado direito (Limite Superior) de suas Métricas históricas, um Alerta é gerado. Um Limite Inferior, Limite Superior ou ambos devem ser definidos.

• Limite Inferior Log Normal

  • Um Limite Inferior em um Teste Log Normal pode ser qualquer decimal positivo entre 0.5 e 1.0. Onde 0.5 representa a localização central e 1.0 representa todos os possíveis valores do lado esquerdo (-∞). É usado quando um valor menor indicaria uma regressão de desempenho.
  • Por exemplo, se você usasse um Teste Log Normal com um Limite Inferior de 0.977 e tivesse 25 Métricas históricas centradas em torno de 100 e um outlier anterior em 200, o Limite Inferior seria 71.20 e qualquer valor inferior a 71.20 geraria um Alerta.

• Limite Superior Log Normal

  • Um Limite Superior em um Teste Log Normal pode ser qualquer decimal positivo entre 0.5 e 1.0. Onde 0.5 representa a localização central e 1.0 representa todos os possíveis valores do lado direito (∞). É usado quando um valor maior indicaria uma regressão de desempenho.
  • Por exemplo, se você usasse um Teste Log Normal com um Limite Superior de 0.977 e tive 25 Métricas históricas centradas em torno de 100 e um outlier anterior em 200, o Limite Superior seria 134.18 e qualquer valor superior a 134.18 geraria um Alerta.

Intervalo Interquartil

Um Teste de Intervalo Interquartil (iqr) mede quantos múltiplos do intervalo interquartil (IQR) uma nova Métrica está acima ou abaixo da mediana de suas Métricas históricas. Se uma nova Métrica estiver abaixo de um certo múltiplo do IQR a partir da mediana (Limite Inferior) ou acima de um certo múltiplo do IQR a partir da mediana (Limite Superior) de suas Métricas históricas, um Alerta será gerado. É necessário definir pelo menos um dos limites: Inferior, Superior ou ambos.

• Limite Inferior do Intervalo Interquartil

  • Um Limite Inferior do Teste de Intervalo Interquartil pode ser qualquer multiplicador maior ou igual a zero (ex: use 2.0 para 2x). É utilizado quando um valor menor indicaria uma regressão de desempenho.
  • Por exemplo, se você tivesse um Teste de Intervalo Interquartil com um Limite Inferior definido como 2.0 e suas Métricas históricas tivessem uma mediana de 100 e um intervalo interquartil de 10, o Limite Inferior seria 80 e qualquer valor menor que 80 geraria um Alerta.

• Limite Superior do Intervalo Interquartil

  • Um Limite Superior do Teste de Intervalo Interquartil pode ser qualquer multiplicador maior ou igual a zero (ex: use 2.0 para 2x). É usado quando um valor maior indicaria uma regressão de desempenho.
  • Por exemplo, se você tivesse um Teste de Intervalo Interquartil com um Limite Superior definido como 2.0 e suas Métricas históricas tivessem uma mediana de 100 e um intervalo interquartil de 10, o Limite Superior seria 120 e qualquer valor maior que 120 geraria um Alerta.

Intervalo Interquartil Delta

Um Teste de Intervalo Interquartil Delta (delta_iqr) mede quantos múltiplos da média da variação percentual (Δ) do intervalo interquartil (IQR) uma nova Métrica está acima ou abaixo da mediana das suas Métricas históricas. Se uma nova Métrica estiver abaixo de um certo múltiplo do ΔIQR da mediana (Limite Inferior) ou acima de um certo múltiplo do ΔIQR da mediana (Limite Superior) das suas Métricas históricas, um Alerta é gerado. Deve-se definir um Limite Inferior, um Limite Superior, ou ambos.

• Limite Inferior do Intervalo Interquartil Delta

  • Um Limite Inferior do Teste de Intervalo Interquartil Delta pode ser qualquer multiplicador maior ou igual a zero (ex: use 2.0 para 2x). É utilizado quando um valor menor indicaria uma regressão de desempenho.
  • Por exemplo, se você tivesse um Teste de Intervalo Interquartil Delta com um Limite Inferior definido para 2.0 e suas Métricas históricas tivessem uma mediana de 100, um intervalo interquartil de 10, e uma média do intervalo interquartil delta de 0.2 (20%), o Limite Inferior seria 60 e qualquer valor menor que 60 geraria um Alerta.

• Limite Superior do Intervalo Interquartil Delta

  • Um Limite Superior do Teste de Intervalo Interquartil Delta pode ser qualquer multiplicador maior ou igual a zero (ex: use 2.0 para 2x). É utilizado quando um valor maior indicaria uma regressão de desempenho.
  • Por exemplo, se você tivesse um Teste de Intervalo Interquartil Delta com um Limite Superior definido para 2.0 e suas Métricas históricas tivessem uma mediana de 100, um intervalo interquartil de 10, e uma média do intervalo interquartil delta de 0.2 (20%), o Limite Superior seria 140 e qualquer valor maior que 140 geraria um Alerta.

Estático

Um Teste Estático (static) é o Teste mais simples. Se uma nova Métrica está abaixo de um Limite Inferior definido ou acima de um Limite Superior definido, um Alerta é gerado. Ou seja, o Limite Inferior/Superior é um Limite Inferior/Superior explícito. Deve-se definir pelo menos um Limite Inferior ou um Limite Superior, ou ambos. Testes Estáticos funcionam melhor quando o valor da Métrica deve permanecer dentro de um intervalo constante em todos os Benchmarks, como cobertura de código.

🐰 Se você deseja um Limite Inferior/Superior Estático diferente para cada Benchmark, você deve usar o Teste de Porcentagem (percentage) com o Limite Inferior/Superior definido para 0.0 e o Tamanho Máximo da Amostra definido para 2.

• Limite Inferior Estático

  • Um Limite Inferior de Teste Estático pode ser qualquer número de ponto flutuante. É usado quando um valor menor indicaria uma regressão de desempenho. O Limite Inferior deve ser menor ou igual ao Limite Superior, se ambos forem especificados.
  • Por exemplo, se você tivesse um Teste Estático com um Limite Inferior definido para 100, o Limite Inferior seria igualmente 100 e qualquer valor menor que 100 geraria um Alerta.

• Limite Superior Estático

  • Um Limite Superior de Teste Estático pode ser qualquer número de ponto flutuante. É usado quando um valor maior indicaria uma regressão de desempenho. O Limite Superior deve ser maior ou igual ao Limite Inferior, se ambos forem especificados.
  • Por exemplo, se você tivesse um Teste Estático com um Limite Superior definido para 100, o Limite Superior seria igualmente 100 e qualquer valor maior que 100 geraria um Alerta.

--threshold-minimum-sample-size <SAMPLE_SIZE>

Opcionalmente, especifique o número mínimo de Métricas necessárias para executar um Teste. Se esse mínimo não for atingido, o Teste não será executado. O tamanho amostral especificado deve ser maior ou igual a 2. Se a opção --threshold-max-sample-size também estiver definida, então o tamanho amostral especificado deve ser menor ou igual a --threshold-max-sample-size. Esta opção não pode ser usada com o Teste Estático (static).

Por exemplo, para usar um Limite com um tamanho mínimo de amostra de 10, você poderia escrever --threshold-min-sample-size 10. Se houvesse menos de 10 Métricas, o Teste não seria executado. Por outro lado, se houvesse 10 ou mais Métricas, o Teste seria executado.

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

Opcionalmente, especifique o número máximo de Métricas usadas para executar um Teste. Se esse máximo for excedido, as Métricas mais antigas serão ignoradas. O tamanho da amostra especificado deve ser maior ou igual a 2. Se a opção --threshold-min-sample-size também estiver definida, então o tamanho da amostra especificado deve ser maior ou igual a --threshold-min-sample-size. Esta opção não pode ser usada com o Teste Estático (static).

Por exemplo, para usar um Limite com um tamanho máximo de amostra de 100, você poderia escrever --threshold-max-sample-size 100. Se houvesse mais de 100 Métricas, apenas as 100 Métricas mais recentes seriam incluídas. Inversamente, se houvesse 100 ou menos Métricas, todas as Métricas seriam incluídas.

--threshold-window <WINDOW>

Opcionalmente, especifique o intervalo de tempo para Métricas usado para realizar o Teste, em segundos. O intervalo especificado deve ser maior que 0. Esta opção não pode ser utilizada com o Teste Estático (static).

Por exemplo, para usar um Limite com um intervalo de quatro semanas ou 2419200 segundos, você poderia escrever --threshold-window 2419200. Se houver quaisquer Métricas mais antigas que quatro semanas, elas seriam excluídas. Por outro lado, se todas as Métricas forem das últimas quatro semanas, todas seriam incluídas.

--threshold-lower-boundary <BOUNDARY>

Especifique o Limite Inferior. As restrições sobre o Limite Inferior dependem do Teste utilizado. O Limite Inferior, o Limite Superior ou ambos devem ser especificados.

Para mais detalhes, consulte a documentação para o Teste específico que você está usando:

• Limite Inferior Percentual
• Limite Inferior z-score
• Limite Inferior do teste t
• Limite Inferior Log Normal
• Limite Inferior do Intervalo Interquartil
• Limite Inferior da Variação do Intervalo Interquartil
• Limite Inferior Estático

--threshold-upper-boundary <BOUNDARY>

Especifique o Limite Superior. As restrições no Limite Superior dependem do Teste utilizado. Ou o Limite Inferior, o Limite Superior, ou ambos devem ser especificados.

Para detalhes, veja a documentação para o teste específico que você está utilizando:

• Percentage Upper Boundary
• z-score Upper Boundary
• t-test Upper Boundary
• Log Normal Upper Boundary
• Interquartile Range Upper Boundary
• Delta Interquartile Range Upper Boundary
• Static Upper Boundary

---thresholds-reset

Redefina todos os Limiares não especificados para o Branch e Testbed dados. Se um Limiar já existe e não for especificado, seu Modelo atual será removido.

Por exemplo, se houver dois Limiares para o Branch main e Testbed localhost:

• Branch main, Testbed localhost, Métrica de latência
• Branch main, Testbed localhost, Métrica de throughput

Se apenas a Métrica de latência for especificada no subcomando bencher run e --thresholds-reset for usado, então a Métrica de throughput terá seu Modelo removido.

--err

Opcionalmente, apresente erro quando um Alerta for gerado./de/ Um Alerta é gerado quando uma nova Métrica está abaixo de um Limite de Limite Inferior ou acima de um Limite de Limite Superior.

Suprimindo Alertas

Às vezes, pode ser útil suprimir Alertas para um Benchmark específico./de/ A melhor maneira de fazer isso é adicionando um destes sufixos especiais ao nome desse Benchmark:

• _bencher_ignore
• BencherIgnore
• -bencher-ignore

Por exemplo, se o seu Benchmark se chamava my_flaky_benchmark, renomeá-lo para my_flaky_benchmark_bencher_ignore faria com que apenas esse Benchmark específico fosse ignorado daqui em diante./de/ Benchmarks ignorados ainda são verificados em relação aos Limites existentes./de/ No entanto, um Alerta não será gerado para eles./de/ As Métricas para Benchmarks ignorados ainda são armazenadas./de/ Os resultados de my_flaky_benchmark_bencher_ignore ainda seriam armazenados como o Benchmark my_flaky_benchmark./de/ Se você remover o sufixo e retornar ao nome original do Benchmark,/de/ então tudo continuará de onde parou.

🐰 Parabéns! Você aprendeu tudo sobre Limites & Alertas! 🎉

Continue: Adaptadores do Harness de Benchmark ➡