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:
🐰 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:
--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:
- Estático (
static
) - Porcentagem (
percentage
) - z-score (
z_score
) - t-test (
t_test
) - Log Normal (
log_normal
) - Intervalo Interquartil (
iqr
) - Delta Intervalo Interquartil (
delta_iqr
)
Por exemplo, para usar um Limite com um teste t de Student,
você poderia escrever --threshold-test t_test
.
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.
-
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 igualmente100
e qualquer valor menor que100
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 igualmente100
e qualquer valor maior que100
geraria um Alerta.
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
para10%
). É 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 de100
, o Limite Inferior seria90
e qualquer valor inferior a90
geraria um Alerta.
- Um Limite Inferior de Teste de Porcentagem pode ser qualquer porcentagem maior ou igual a zero em forma decimal (ex: use
-
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
para10%
). É 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 de100
, o Limite Superior seria110
e qualquer valor maior que110
geraria um Alerta.
- Um Limite Superior de Teste de Porcentagem pode ser qualquer porcentagem maior ou igual a zero em forma decimal (ex: use
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
e1.0
. Onde0.5
representa a média e1.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 de100
e um desvio padrão de10
, o Limite Inferior seria80.05
e qualquer valor inferior a80.05
geraria um Alerta.
- Um Limite Inferior de Teste de z-score pode ser qualquer decimal positivo entre
-
Limite Superior do z-score
- Um Limite Superior de Teste de z-score pode ser qualquer decimal positivo entre
0.5
e1.0
. Onde0.5
representa a média e1.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 de100
e um desvio padrão de10
, o Limite Superior seria119.95
e qualquer valor superior a119.95
geraria um Alerta.
- Um Limite Superior de Teste de z-score pode ser qualquer decimal positivo entre
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
e1.0
. Onde0.5
representa a média e1.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 tinha25
Métricas históricas com uma média de100
e um desvio padrão de10
, o Limite Inferior seria78.96
e qualquer valor inferior a78.96
geraria um Alerta.
- Um Limite Inferior do Teste t-test pode ser qualquer decimal positivo entre
-
Limite Superior do t-test
- Um Limite Superior do Teste t-test pode ser qualquer decimal positivo entre
0.5
e1.0
. Onde0.5
representa a média e1.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 tinha25
Métricas históricas com uma média de100
e um desvio padrão de10
, o Limite Superior seria121.04
e qualquer valor superior a121.04
geraria um Alerta.
- Um Limite Superior do Teste t-test pode ser qualquer decimal positivo entre
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
e1.0
. Onde0.5
representa a localização central e1.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 tivesse25
Métricas históricas centradas em torno de100
e um outlier anterior em200
, o Limite Inferior seria71.20
e qualquer valor inferior a71.20
geraria um Alerta.
- Um Limite Inferior em um Teste Log Normal pode ser qualquer decimal positivo entre
-
Limite Superior Log Normal
- Um Limite Superior em um Teste Log Normal pode ser qualquer decimal positivo entre
0.5
e1.0
. Onde0.5
representa a localização central e1.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 tive25
Métricas históricas centradas em torno de100
e um outlier anterior em200
, o Limite Superior seria134.18
e qualquer valor superior a134.18
geraria um Alerta.
- Um Limite Superior em um Teste Log Normal pode ser qualquer decimal positivo entre
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
para2x
). É 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 de100
e um intervalo interquartil de10
, o Limite Inferior seria80
e qualquer valor menor que80
geraria um Alerta.
- Um Limite Inferior do Teste de Intervalo Interquartil pode ser qualquer multiplicador maior ou igual a zero (ex: use
-
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
para2x
). É 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 de100
e um intervalo interquartil de10
, o Limite Superior seria120
e qualquer valor maior que120
geraria um Alerta.
- Um Limite Superior do Teste de Intervalo Interquartil pode ser qualquer multiplicador maior ou igual a zero (ex: use
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
para2x
). É 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 de100
, um intervalo interquartil de10
, e uma média do intervalo interquartil delta de0.2
(20%
), o Limite Inferior seria60
e qualquer valor menor que60
geraria um Alerta.
- Um Limite Inferior do Teste de Intervalo Interquartil Delta pode ser qualquer multiplicador maior ou igual a zero (ex: use
-
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
para2x
). É 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 de100
, um intervalo interquartil de10
, e uma média do intervalo interquartil delta de0.2
(20%
), o Limite Superior seria140
e qualquer valor maior que140
geraria um Alerta.
- Um Limite Superior do Teste de Intervalo Interquartil Delta pode ser qualquer multiplicador maior ou igual a zero (ex: use
--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 Estático
- 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
--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:
- Static Upper Boundary
- Percentage Upper Boundary
- z-score Upper Boundary
- t-test Upper Boundary
- Log Normal Upper Boundary
- Interquartile Range Upper Boundary
- Delta Interquartile Range 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
, Testbedlocalhost
, Métrica delatência
- Branch
main
, Testbedlocalhost
, Métrica dethroughput
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! 🎉