Benchmarking honnête

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

En bref

Un chiffre de benchmark sans sa méthode ne t’apprend presque rien. « NextPDF rend un document en N millisecondes » ne t’apprend rien tant que tu ne connais pas le document, le matériel, le nombre d’exécutions et la variance. Cette page explique comment NextPDF mesure la performance, pourquoi il présente un signal validé plutôt qu’un chiffre d’accroche, et pourquoi elle ne donne aucun chiffre de vitesse.

Pourquoi c’est important

Les promesses de performance font partie des chiffres les plus faciles à publier et à fausser — le plus souvent par accident. Une seule exécution à chaud sur un portable au repos, le meilleur résultat sur dix tentatives, un micro-benchmark d’une fonction que personne n’appelle sur un chemin critique : chacun produit un chiffre réel qui ne prédit rien pour ta propre charge de travail. Spec: ISO/IEC 25010 définit l’efficacité de la performance comme l’exécution de fonctions dans des paramètres de temps et de débit dans des conditions spécifiées (ISO/IEC 25010, §3.10). Retire « dans des conditions spécifiées » et le chiffre cesse d’être une mesure. Il devient un nombre dénué de sens.

Il existe aussi un échec plus discret : un chiffre qui a été vrai une fois. Dès l’instant où tu colles un résultat de benchmark dans un texte, il se fige. Pendant ce temps, le code, l’environnement d’exécution et le matériel continuent de changer. Une promesse de « rapidité » périmée n’est pas seulement inutile. Elle est fausse, et elle l’est silencieusement.

La version courte

Un chiffre de performance n’a aucun sens sans sa méthode : l’entrée, l’environnement, le nombre d’exécutions, la politique de préchauffage et la dispersion.
NextPDF mesure avec des exécutions répétées, écarte les itérations de préchauffage et présente une distribution, et non un seul chiffre du meilleur cas.
La détection de régression est statistique : un résultat est évalué par rapport à une référence avec le test t de Welch, de sorte qu’un changement doit être à la fois statistiquement significatif et suffisamment important avant d’être qualifié de régression.
Un environnement instable est détecté et signalé, et non masqué silencieusement par une moyenne — une forte variance d’une exécution à l’autre invalide le résultat au lieu de se dissimuler dans la moyenne.
La performance est publiée comme un signal vivant généré avec la version, jamais comme un slogan figé — c’est pourquoi aucun chiffre en millisecondes n’apparaît sur cette page.

Comment NextPDF l’aborde

Le verrou de performance du moteur est un test statistique, pas une unique exécution chronométrée. Sa méthodologie documentée exécute la suite mesurée à plusieurs reprises, écarte un nombre configuré d’exécutions de préchauffage, puis calcule la moyenne, l’écart-type et le coefficient de variation pour la durée comme pour la mémoire. Il compare ensuite le résultat courant à une référence validée :

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.

Comment le verrou de benchmark de NextPDF décide entre réussite, échec ou résultat non fiable : prendre des mesures répétées, écarter les préchauffages, résumer la distribution, puis appliquer le test t de Welch face à une référence validée. Une régression exige une significativité statistique ET une taille d'effet matérielle ; une variance excessive est signalée comme non fiable plutôt que moyennée dans un verdict.

Trois propriétés rendent l’approche honnête. Premièrement, une régression requiert deux choses à la fois : une significativité statistique (la différence a peu de chances d’être du bruit) et une taille d’effet supérieure à un seuil (la différence est assez grande pour compter). Un ralentissement minuscule mais réel ne déclenche pas de fausse alerte. Un ralentissement important dans des données bruitées n’est pas ignoré. Deuxièmement, l’instabilité est un verdict : lorsque la variation d’une exécution à l’autre dépasse une borne, le verrou signale l’environnement comme non fiable. Il ne calcule pas une moyenne dénuée de sens pour la déclarer réussie. Troisièmement, il reste un plafond absolu — une borne supérieure stricte qui fait échouer la version quelles que soient les statistiques. Grâce à lui, « aucune régression significative » ne peut jamais excuser un résultat déjà trop lent.

C’est la discipline de mesure décrite par ISO/IEC 17025 pour toute métrique crédible : des résultats obtenus dans des conditions prédéterminées — la répétabilité au sein d’un même environnement (ISO/IEC 17025, §3.7) et la reproductibilité d’un environnement à l’autre (ISO/IEC 17025, §3.5). Un chiffre de performance de NextPDF n’a de sens que comme « cette méthode, cette référence, cette exécution ». C’est exactement pourquoi il vit avec la version qui l’a produit, et non dans une phrase ici.

Ce que disent les preuves

Evidence: Benchmark-backed Le verrou de benchmark du moteur met en œuvre des mesures répétées avec écartement du préchauffage, un résumé par moyenne / écart-type / coefficient de variation, et un test t de Welch à deux échantillons face à une référence validée, avec des verdicts explicites : réussite / régression / non fiable / échec de plafond strict. Les benchmarks de performance existent aussi sous forme d’une suite dédiée, exécutable séparément, ainsi que d’un harnais PHPBench. La performance est mesurée délibérément, et non estimée.

Evidence: Standard-backed « Dans des conditions spécifiées » n’est pas une précaution rédactionnelle. C’est la définition. Spec: ISO/IEC 25010, §3.10 rattache l’efficacité de la performance à des conditions spécifiées de temps, de débit et de ressources. Un chiffre sans ses conditions n’est pas une mesure affaiblie. Ce n’est pas une mesure.

Evidence: Standard-backed Le cadrage par répétabilité et reproductibilité suit Spec: ISO/IEC 17025 : un résultat n’est crédible que par rapport à des conditions prédéterminées, distinguant la répétabilité au sein d’un même environnement de la reproductibilité d’un environnement à l’autre. Un benchmark qui ne peut énoncer ses conditions ne peut se réclamer ni de l’une ni de l’autre.

Exemple concret

Voilà à quoi ressemble « honnête » en pratique : un énoncé de méthode, et non un chiffre :

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

Le livrable d’un benchmark, c’est la méthode reproductible et le verdict. La valeur brute en millisecondes appartient à la version qui l’a produite, où tu peux la recalculer — pas à une documentation où tu ne le peux pas.

Idée fausse fréquente

La première idée fausse consiste à croire qu’un benchmark est un chiffre. Un benchmark est une procédure qui produit une distribution. Le chiffre n’en est qu’un seul tirage. Retenir le meilleur de plusieurs exécutions, ou une unique exécution à chaud, n’est pas optimiste. C’est mesurer autre chose (le pic dans des conditions idéales) et l’étiqueter comme une performance typique.

La seconde consiste à croire que « aucune régression statistiquement significative » signifie « aussi rapide qu’avant, garanti ». Cela signifie que la différence observée se situe dans ce que la méthode peut distinguer du bruit, compte tenu de ce nombre d’exécutions et de cette variance. C’est un énoncé borné et conditionnel. C’est précisément pourquoi NextPDF conserve le plafond absolu comme garde-fou indépendant et refuse de comprimer le résultat en une promesse non qualifiée — pour lui-même comme pour quiconque.

Limites et frontières

Cette page décrit comment NextPDF mesure et présente la performance. Elle n’énonce volontairement aucun chiffre de débit, de latence ou de mémoire. Ce sont des signaux vivants générés à partir des artefacts d’intégration continue dans des conditions énoncées, et les valeurs courantes sont publiées avec la version. Un chiffre répété ici serait détaché de ses conditions et deviendrait périmé — l’échec même contre lequel cette page argumente. Il n’existe aucune constante de performance stable à citer, donc aucune n’est citée. La discipline est le livrable.

Le nombre d’exécutions, la politique de préchauffage, les seuils et la référence relèvent de la configuration de benchmark du moteur et évoluent avec le moteur et son matériel. Cette configuration fait autorité si elle diverge un jour de la présente explication. NextPDF n’établit aucune comparaison de performance avec une autre bibliothèque — favorable ou défavorable — car une telle comparaison sans conditions identiques et énoncées serait exactement la promesse non qualifiée que cette page existe pour refuser.

Documents liés

Tests par fichiers de référence — la même discipline de reproductibilité appliquée à la justesse de la sortie, y compris les profils binaire / structurel / sémantique.
La pyramide de tests de NextPDF — où se place le palier de performance et pourquoi il est optionnel plutôt qu’appliqué à chaque changement.
Les tests par mutation, expliqués — un autre endroit où NextPDF présente un signal validé plutôt qu’un indicateur de vanité.

Glossaire

Benchmark — une procédure définie qui produit une distribution de mesures dans des conditions énoncées, et non un chiffre unique.
Exécution de préchauffage — une itération initiale écartée afin que les effets de démarrage à froid (JIT, caches, autoload) ne contaminent pas le résultat mesuré.
Coefficient de variation — l’écart-type divisé par la moyenne ; une mesure sans unité de la dispersion utilisée pour juger si une exécution est assez stable pour qu’on puisse s’y fier.
Test t de Welch — un test statistique à deux échantillons à variances inégales, utilisé ici pour décider si un résultat diffère de la référence au-delà du bruit.
Taille d’effet — l’ampleur d’une différence, indépendamment de la significativité statistique ; NextPDF exige les deux avant de déclarer une régression.
Répétabilité / reproductibilité — la concordance des résultats dans des conditions prédéterminées au sein d’un même environnement (répétabilité) ou d’un environnement à l’autre (reproductibilité), selon ISO/IEC 17025.
Plafond absolu — une borne supérieure stricte qui fait échouer la version quelle que soit la comparaison statistique.