Benchmarking onesto

Spec: ISO/IEC 25010 Spec: ISO/IEC 17025 Evidence: Benchmark-backed

In sintesi

Un dato di benchmark senza il metodo che lo produce dice poco o nulla. «NextPDF esegue il rendering di un documento in N millisecondi» non significa nulla se non si conoscono il documento, l’hardware, il numero di esecuzioni e la varianza. Questa pagina spiega come NextPDF misura le prestazioni, perché riporta un segnale validato anziché un dato a effetto e perché non contiene alcun valore di velocità.

Perché è importante

Le affermazioni sulle prestazioni sono tra i dati più facili da pubblicare e da falsare, spesso per caso. Una singola esecuzione a caldo su un portatile inattivo, il risultato più veloce fra dieci tentativi, un microbenchmark di una funzione che nessuno chiama in un percorso critico: tutti producono dati reali che non predicono nulla del proprio carico di lavoro. Spec: ISO/IEC 25010 definisce l’efficienza delle prestazioni come l’esecuzione di funzioni entro parametri di tempo e di throughput in condizioni specificate (ISO/IEC 25010, §3.10). Se si toglie «in condizioni specificate», il dato smette di essere una misurazione. Diventa privo di significato.

Esiste anche un fallimento più silenzioso: un dato che è stato vero una volta sola. Nel momento in cui si incolla un risultato di benchmark in un testo, lo si congela. Nel frattempo codice, runtime e hardware continuano a cambiare. Un’affermazione «veloce» obsoleta non è soltanto inutile. È sbagliata, e lo è senza farsi notare.

In breve

Un dato sulle prestazioni è privo di significato senza il proprio metodo: input, ambiente, numero di esecuzioni, politica di warmup e dispersione.
NextPDF misura con esecuzioni ripetute, scarta le iterazioni di warmup e riporta una distribuzione, non il singolo dato migliore.
Il rilevamento delle regressioni è statistico: un risultato viene valutato rispetto a una baseline con il test t di Welch, quindi una variazione deve essere sia statisticamente significativa sia abbastanza grande da contare prima di essere considerata una regressione.
Un ambiente instabile viene rilevato e segnalato, non assorbito in una media silenziosa — una varianza elevata tra le esecuzioni invalida il risultato anziché nascondersi nella media.
Le prestazioni sono pubblicate come segnale vivo generato con la build, mai come titolo a effetto congelato — ed è per questo che in questa pagina non compare alcun valore in millisecondi.

Come NextPDF lo affronta

Il gate delle prestazioni del motore è un test statistico, non una singola esecuzione cronometrata. La metodologia documentata esegue più volte la suite misurata, scarta un numero configurato di esecuzioni di warmup e calcola media, deviazione standard e coefficiente di variazione sia per la durata sia per la memoria. Confronta poi il risultato corrente con una baseline registrata nel commit:

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

Come il gate di benchmark di NextPDF decide tra superato, fallito o inaffidabile: eseguire misurazioni ripetute, scartare i warmup, riepilogare la distribuzione, quindi applicare il test t di Welch rispetto a una baseline registrata nel commit. Una regressione richiede significatività statistica E una dimensione dell'effetto rilevante; una varianza eccessiva viene segnalata come inaffidabile anziché mediata in un verdetto.

Tre proprietà rendono onesto questo approccio. Primo, una regressione richiede due cose insieme: significatività statistica (è improbabile che la differenza sia rumore) e una dimensione dell’effetto oltre una soglia (la differenza è abbastanza grande da contare). Un rallentamento minimo ma reale non genera un falso allarme. Un rallentamento grande in dati rumorosi non passa sotto traccia. Secondo, l’instabilità è un verdetto: quando la variazione tra le esecuzioni supera un limite, il gate segnala l’ambiente come inaffidabile. Non calcola una media priva di significato per poi dichiararla un successo. Terzo, esiste comunque un tetto assoluto — un limite superiore rigido che fa fallire la build indipendentemente dalla statistica. Grazie a esso, «nessuna regressione significativa» non può mai giustificare un risultato già troppo lento.

È la disciplina di misurazione che ISO/IEC 17025 descrive per qualsiasi metrica credibile: risultati ottenuti in condizioni predeterminate — ripetibilità all’interno di un unico ambiente (ISO/IEC 17025, §3.7) e riproducibilità tra ambienti diversi (ISO/IEC 17025, §3.5). Un dato sulle prestazioni di NextPDF ha significato solo come «questo metodo, questa baseline, questa esecuzione». È proprio per questo che resta con la build che lo ha prodotto, non in una frase in questa pagina.

Cosa dicono le evidenze

Evidence: Benchmark-backed Il gate di benchmark del motore implementa misurazioni ripetute con scarto del warmup, riepilogo di media / deviazione standard / coefficiente di variazione e un test t di Welch a due campioni rispetto a una baseline registrata nel commit, con esiti espliciti di superato / regressione / instabile / superamento del tetto rigido. I benchmark delle prestazioni esistono inoltre come suite dedicata ed eseguibile separatamente e come harness PHPBench. Le prestazioni vengono misurate deliberatamente, non stimate.

Evidence: Standard-backed «In condizioni specificate» non è una cautela editoriale: è la definizione. Spec: ISO/IEC 25010, §3.10 lega l’efficienza delle prestazioni a condizioni specificate di tempo, throughput e risorse. Un dato senza le proprie condizioni non è una misurazione più debole: non è una misurazione.

Evidence: Standard-backed L’inquadramento di ripetibilità e riproducibilità segue Spec: ISO/IEC 17025 : un risultato è credibile solo rispetto a condizioni predeterminate, distinguendo la ripetibilità nello stesso ambiente dalla riproducibilità tra ambienti diversi. Un benchmark che non sa dichiarare le proprie condizioni non può rivendicare né l’una né l’altra.

Esempio pratico

Nella pratica, «onesto» significa dichiarare un metodo, non esibire un dato:

<?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.

Il prodotto di un benchmark è il metodo riproducibile e il verdetto. Il valore grezzo in millisecondi appartiene alla build che lo ha prodotto, dove lo si può ricavare di nuovo — non a una documentazione in cui non è possibile verificarlo.

Equivoco comune

Il primo equivoco è che un benchmark sia un dato. Un benchmark è una procedura che produce una distribuzione. Il dato è solo un’estrazione da essa. Riportare la migliore fra diverse esecuzioni, o una singola esecuzione a caldo, non è ottimistico: significa misurare una cosa diversa (il picco in condizioni ideali) ed etichettarla come prestazione tipica.

Il secondo è che «nessuna regressione statisticamente significativa» significhi «veloce come prima, garantito». Significa che la differenza osservata rientra in ciò che il metodo riesce a distinguere dal rumore, dato questo numero di esecuzioni e questa varianza. È un’affermazione limitata e condizionata. È esattamente per questo che NextPDF mantiene il tetto assoluto come salvaguardia indipendente e rifiuta di comprimere il risultato in un’affermazione non qualificata — che vada a proprio favore o contro chiunque altro.

Limiti e confini

Questa pagina descrive come NextPDF misura e riporta le prestazioni. Di proposito non riporta alcun dato di throughput, latenza o memoria. Quei dati sono segnali vivi generati dagli artefatti di integrazione continua in condizioni dichiarate, e i valori correnti sono pubblicati con la build. Un dato ripetuto qui sarebbe privo di condizioni e diventerebbe obsoleto — proprio il fallimento contro cui questa pagina argomenta. Non esiste una costante di prestazione stabile da citare, perciò non se ne cita alcuna. La disciplina è il prodotto.

Il numero di esecuzioni, la politica di warmup, le soglie e la baseline sono di competenza della configurazione di benchmark del motore ed evolvono con il motore e il suo hardware. Quella configurazione è l’autorità qualora dovesse mai discordare da questa spiegazione. NextPDF non effettua alcun confronto di prestazioni con qualsiasi altra libreria — favorevole o sfavorevole — perché un confronto simile, senza condizioni identiche e dichiarate, sarebbe esattamente l’affermazione non qualificata che questa pagina esiste per rifiutare.

Documentazione correlata

Test su file golden — la stessa disciplina di riproducibilità applicata alla correttezza dell’output, inclusi i profili bitwise / strutturale / semantico.
La piramide dei test di NextPDF — dove si colloca il livello delle prestazioni e perché è opzionale anziché eseguito a ogni modifica.
Il mutation testing, spiegato — un altro punto in cui NextPDF riporta un segnale validato anziché un dato di facciata.

Glossario

Benchmark — una procedura definita che produce una distribuzione di misurazioni in condizioni dichiarate, non un singolo dato.
Esecuzione di warmup — un’iterazione iniziale scartata affinché gli effetti di avvio a freddo (JIT, cache, autoload) non contaminino il risultato misurato.
Coefficiente di variazione — la deviazione standard divisa per la media; una misura adimensionale della dispersione usata per valutare se un’esecuzione è abbastanza stabile da essere affidabile.
Test t di Welch — un test statistico a due campioni per varianze diseguali, qui usato per decidere se un risultato differisce dalla baseline oltre il rumore.
Dimensione dell’effetto — quanto è grande una differenza, indipendentemente dalla significatività statistica; NextPDF richiede entrambe prima di dichiarare una regressione.
Ripetibilità / riproducibilità — concordanza dei risultati in condizioni predeterminate all’interno di un unico ambiente (ripetibilità) o tra ambienti diversi (riproducibilità), secondo ISO/IEC 17025.
Tetto assoluto — un limite superiore rigido che fa fallire la build indipendentemente dal confronto statistico.