Benchmark de uma alteração: warm-up, repetições, variância e o que reportar

Objetivo

Produzir uma comparação de tempos entre duas versões de uma função, consulta ou comando que outra pessoa consiga reproduzir e que não apresente ruído como se fosse uma melhoria.

Pré-requisitos

Uma máquina sem mais nada em execução (um laptop ligado à tomada, com perfil de energia fixo, ou um host dedicado), as entradas exatas, as versões do interpretador ou do compilador e uma decisão sobre o que se mede: o tempo de relógio (wall-clock) de um comando inteiro ou um microbenchmark de uma única função.

Passos

1. Fixe a carga de trabalho antes de executar qualquer coisa: os mesmos dados de entrada, o mesmo tamanho e a mesma configuração, registrados no script do benchmark.
2. Faça o warm-up. Descarte as primeiras execuções para que caches de arquivos, compiladores JIT e inicialização lazy não prejudiquem uma das variantes. O hyperfine tem --warmup N para comandos inteiros e, para a pergunta oposta, --prepare, que executa um comando de limpeza de cache antes de cada medição.
3. Repita de forma intercalada. Execute cada variante muitas vezes na ordem A, B, A, B, e não primeiro todas as de A e depois todas as de B, para que a deriva da máquina (thermal throttling, uma tarefa em segundo plano) afete ambas por igual.
4. Escolha a estatística antes de olhar os dados. A documentação do timeit do Python afirma que o menor valor dá um limite inferior de quão rápido a máquina consegue executar o trecho de código, que valores mais altos costumam vir de outros processos que interferem, e que se deve olhar para o vetor de resultados completo em vez de reportar média e desvio padrão. Isso serve para microbenchmarks limitados pela CPU; para o throughput de todo o sistema com I/O, medianas e percentis descrevem o que os usuários veem.
5. Registre a dispersão: o número de execuções e o mínimo, a mediana e o máximo (ou uma dispersão por percentis) de cada variante. O hyperfine faz detecção estatística de outliers para sinalizar interferência de outros programas e efeitos de cache; uma execução sinalizada é motivo para repetir, não um dado a apagar em silêncio.
6. Anote o ambiente: modelo da CPU, escalonamento de frequência, limites de CPU do contêiner, versão da linguagem e se o garbage collection foi desativado (por padrão, o timeit o desliga durante a medição).
7. Reporte os números, o comando exato, o ambiente e a regra de comparação. Uma diferença menor que a dispersão entre execuções não é um resultado.

Resultado esperado

Uma tabela em que cada variante tem N execuções, mínimo/mediana/máximo e um ambiente declarado, junto com o script que a gerou; quem a ler consegue repetir o teste e obter valores dentro da dispersão reportada.

Limites e base de verificação

Um microbenchmark mede uma função isoladamente; o efeito no programa real pode ser menor (a função não é crítica para o desempenho) ou maior (efeitos de cache e de alocação). Runners de CI compartilhados acrescentam ruído que nenhuma estatística elimina; se o mínimo é a estatística mais robusta nesse contexto é objeto de uma hipótese separada nesta wiki. Baseado na documentação citada; não se afirma nenhuma medição.