Benchmarking honesto

Spec: ISO/IEC 25010Spec: ISO/IEC 17025

Visão geral

Um número de benchmark sem o método diz muito pouco. “O NextPDF renderiza um documento em N milissegundos” não diz muita coisa para você, a menos que você conheça o documento, o hardware, o número de execuções e a variância. Esta página explica como o NextPDF mede desempenho, por que reporta um sinal controlado em vez de um número de destaque e por que não publica nenhum número de velocidade.

Por que isso importa

Afirmações de desempenho são fáceis de publicar e fáceis de falsear, muitas vezes por acidente. Uma única execução aquecida em um laptop ocioso, o resultado mais rápido entre dez tentativas ou um microbenchmark de uma função que ninguém chama em um caminho crítico podem produzir um número real que não prevê nada para a carga de trabalho. Spec: ISO/IEC 25010 define eficiência de desempenho como executar funções dentro de parâmetros de tempo e de vazão sob condições especificadas (ISO/IEC 25010, §3.10). Remova “sob condições especificadas” e o número deixa de ser uma medição. Ele se torna um valor sem sentido.

Há também uma falha mais silenciosa: um número que já foi verdadeiro um dia. No instante em que você coloca um resultado de benchmark em um texto, ele fica congelado. Enquanto isso, o código, o runtime e o hardware continuam mudando. Uma afirmação desatualizada de “rápido” não é apenas inútil. Ela está errada, e está errada sem avisar.

A versão resumida

Um número de desempenho não significa nada sem o método: a entrada, o ambiente, o número de execuções, a política de aquecimento e a dispersão.
O NextPDF mede com execuções repetidas, descarta as iterações de aquecimento e reporta uma distribuição, não um único valor de melhor caso.
A detecção de regressões é estatística: um resultado é avaliado em relação a uma baseline com o teste t de Welch, de modo que uma mudança precisa ser ao mesmo tempo estatisticamente significativa e grande o bastante para importar antes de contar como uma regressão.
Um ambiente instável é detectado e reportado, e não diluído silenciosamente em uma média — a alta variância entre execuções invalida o resultado em vez de se esconder na média.
O desempenho é publicado como um sinal vivo gerado junto com a build, nunca como um número de destaque congelado — e é por isso que nenhum valor em milissegundos aparece nesta página.

Como o NextPDF aborda isso

O gate de desempenho do mecanismo é um teste estatístico, não uma única execução cronometrada. A metodologia documentada executa a suíte sob medição muitas vezes, descarta um número configurado de execuções de aquecimento e calcula a média, o desvio padrão e o coeficiente de variação tanto para a duração quanto para a memória. Em seguida, compara o resultado atual com uma baseline versionada:

RepeatRun the measured suite N times under fixed conditions.
Discard warmupDrop the first W runs so cold-start noise is excluded.
SummariseCompute mean, standard deviation, and coefficient of variation for duration and memory.
Test vs baselineWelch's t-test (two-sample, unequal variance) against the committed baseline.
DecideSignificant AND effect over threshold → regression. Variance over threshold → unreliable, not a pass. Absolute ceiling breach → hard fail.

Como o gate de benchmark do NextPDF decide entre aprovado, reprovado ou não confiável: faz medições repetidas, descarta os aquecimentos, resume a distribuição e então aplica o teste t de Welch em relação a uma baseline versionada. Uma regressão exige significância estatística E um tamanho de efeito relevante; a variância excessiva é reportada como não confiável em vez de ser diluída em um veredito por meio da média.

Três propriedades mantêm o processo honesto. Primeiro, uma regressão precisa de duas coisas ao mesmo tempo: significância estatística (é improvável que a diferença seja ruído) e um tamanho de efeito acima de um limiar (a diferença é grande o bastante para importar). Uma desaceleração real, mas minúscula, não dispara um alarme falso. Uma desaceleração grande em dados ruidosos não passa despercebida. Segundo, a instabilidade é um veredito: quando a variação entre execuções ultrapassa um limite, o gate reporta o ambiente como não confiável. Ele não dilui o ruído em uma média sem significado nem a trata como aprovação. Terceiro, ainda existe um teto absoluto — um limite superior rígido que reprova a build independentemente das estatísticas. Por causa dele, “nenhuma regressão significativa” nunca pode justificar um resultado que já é lento demais.

Essa é a disciplina de medição que a ISO/IEC 17025 descreve para qualquer métrica confiável: resultados obtidos sob condições predeterminadas — repetibilidade dentro de um mesmo ambiente (ISO/IEC 17025, §3.7) e reprodutibilidade entre ambientes (ISO/IEC 17025, §3.5). Um valor de desempenho do NextPDF só tem significado como “este método, esta baseline, esta execução”. É exatamente por isso que ele fica na build que o produziu, não em uma frase aqui.

Exemplo prático

Na prática, “honesto” tem a forma de uma declaração de método, não de um valor:

<?php

declare(strict_types=1);

// The gate is invoked with its conditions made explicit, e.g.:
//
//   php ci/scripts/benchmark-gate.php \
//       --runs=5 --warmup=1 --testsuite=Unit \
//       --baseline=<committed-baseline>
//
// It then reports, for duration AND memory:
//   - mean, standard deviation, coefficient of variation (the spread)
//   - Welch's t-test p-value and effect size vs the baseline
//   - a verdict: PASS | REGRESSION | UNSTABLE | hard-ceiling FAIL
//
// An honest performance statement is therefore shaped like:
//   "<suite>, <runs> runs (<warmup> warmup), <hardware/runtime>,
//    no statistically significant regression vs baseline <id>;
//    coefficient of variation within bound."
//
// It is NEVER shaped like:
//   "NextPDF is fast" — or a bare millisecond number with no method.

O entregável de um benchmark é o método reproduzível e o veredito. O valor bruto em milissegundos pertence à build que o produziu, onde você pode obtê-lo de novo — não a uma documentação em que você não pode.

Equívoco comum

O primeiro equívoco é achar que um benchmark é um número. Um benchmark é um procedimento que produz uma distribuição. O número é apenas uma amostra dessa distribuição. Reportar o melhor entre várias execuções, ou uma única execução aquecida, não é otimismo. É medir outra coisa (o pico sob condições ideais) e rotulá-la como desempenho típico.

O segundo é achar que “nenhuma regressão estatisticamente significativa” significa “tão rápido quanto antes, garantido”. Significa que a diferença observada está dentro daquilo que o método consegue distinguir do ruído, dado este número de execuções e esta variância. Essa é uma afirmação limitada e condicional. É precisamente por isso que o NextPDF mantém o teto absoluto como uma salvaguarda independente e se recusa a comprimir o resultado em uma afirmação sem qualificação — seja em benefício próprio, seja contra qualquer outra pessoa.

Limites e fronteiras

Esta página descreve como o NextPDF mede e reporta desempenho. Ela não declara nenhum valor de vazão, latência ou memória, de propósito. Esses são sinais vivos gerados a partir de artefatos de integração contínua sob condições declaradas, e os valores atuais são publicados junto com a build. Um número repetido aqui perderia as condições associadas e ficaria desatualizado — exatamente a falha contra a qual esta página argumenta. Não existe nenhuma constante de desempenho estável a citar, então nenhuma é citada. A disciplina é o entregável.

O número de execuções, a política de aquecimento, os limiares e a baseline pertencem à configuração de benchmark do mecanismo e evoluem junto com o mecanismo e o seu hardware. Essa configuração é a autoridade se algum dia divergir desta explicação. O NextPDF não faz nenhuma comparação de desempenho com qualquer outra biblioteca — favorável ou desfavorável — porque uma comparação assim, sem condições idênticas e declaradas, seria exatamente a afirmação sem qualificação que esta página existe para recusar.

Documentação relacionada

Testes de golden file — a mesma disciplina de reprodutibilidade aplicada à correção da saída, incluindo os perfis bitwise / estrutural / semântico.
A pirâmide de testes do NextPDF — onde se encaixa o nível de desempenho e por que ele é opcional, em vez de rodar a cada mudança.
Teste de mutação, explicado — outro lugar em que o NextPDF reporta um sinal controlado em vez de um número de vaidade.

Glossário

Benchmark — um procedimento definido que produz uma distribuição de medições sob condições declaradas, não um único número.
Execução de aquecimento — uma iteração inicial descartada para que os efeitos de partida a frio (JIT, caches, autoload) não contaminem o resultado medido.
Coeficiente de variação — o desvio padrão dividido pela média; uma medida de dispersão sem unidade usada para avaliar se uma execução é estável o suficiente para ser confiável.
Teste t de Welch — um teste estatístico de duas amostras para variâncias desiguais, usado aqui para decidir se um resultado difere da baseline além do ruído.
Tamanho de efeito — quão grande é uma diferença, independentemente da significância estatística; o NextPDF exige ambos antes de declarar uma regressão.
Repetibilidade / reprodutibilidade — a concordância dos resultados sob condições predeterminadas dentro de um mesmo ambiente (repetibilidade) ou entre ambientes (reprodutibilidade), conforme a ISO/IEC 17025.
Teto absoluto — um limite superior rígido que reprova a build independentemente da comparação estatística.