autocannon : Test de charge HTTP Node.js (Guide pas à pas)

Vous avez écrit un point de terminaison HTTP. Il fonctionne lorsque vous l'appelez une fois depuis Postman. Mais que se passe-t-il lorsque 200 clients l'appellent simultanément ? Vous avez besoin de chiffres : requêtes par seconde, centiles de latence et nombre de réponses renvoyées avec un statut autre que 2xx. autocannon vous donne ces chiffres depuis votre terminal en une dizaine de secondes.

autocannon est un outil de benchmarking HTTP/1.1 écrit en Node.js. Il envoie un flux contrôlé de requêtes vers une URL et rapporte le débit et la latence. Ce guide vous accompagne à travers l'installation, une exécution de base, tous les drapeaux que vous utiliserez réellement, la lecture des résultats et l'utilisation d'autocannon depuis un script Node. Il établit également une distinction claire entre ce qu'un test de charge vous dit et ce qu'il ne vous dit pas, afin que vous sachiez quand opter pour un test fonctionnel et de contrat à la place.

bouton

Qu'est-ce qu'autocannon

autocannon ouvre un nombre fixe de connexions concurrentes à une URL et continue d'envoyer des requêtes pendant une durée déterminée (ou un nombre de requêtes défini). Pendant son exécution, il échantillonne la latence et compte les réponses. Une fois terminé, il affiche un tableau des centiles de latence et un résumé du nombre total de requêtes et d'octets lus.

Il mesure une seule chose : la charge que votre serveur supporte et la vitesse à laquelle il répond sous cette charge. Il ne vérifie pas si le corps de la réponse est correct, si votre API correspond à sa spécification OpenAPI, ou si un flux de travail en plusieurs étapes renvoie les bonnes données à chaque étape. Gardez cette distinction à l'esprit. Elle détermine la place d'autocannon dans votre pile de tests, abordée vers la fin.

Si vous avez utilisé wrk ou Apache Bench, autocannon remplit la même fonction avec une installation Node native et une API programmable que vous pouvez appeler depuis JavaScript.

Installation

autocannon est livré sous forme de package npm. Installez-le globalement pour disposer de la commande autocannon partout :

npm i autocannon -g

Vous devez d'abord avoir Node.js installé. Si vous préférez ne pas l'installer globalement, exécutez-le à la demande avec npx :

npx autocannon http://localhost:3000

Ou ajoutez-le à un projet comme dépendance de développement lorsque vous prévoyez de le scripter :

npm i autocannon --save-dev

Vérifiez l'installation :

autocannon --version

Exécution de base

La forme la plus simple est la commande suivie d'une URL. Cela exécute le benchmark par défaut : 10 connexions pendant 10 secondes.

autocannon http://localhost:3000

Ajustez les paramètres avec trois drapeaux que vous utiliserez constamment. -c définit le nombre de connexions concurrentes, -d définit la durée en secondes, et -p définit le pipelining (combien de requêtes chaque connexion envoie avant d'attendre une réponse).

autocannon -c 100 -d 30 -p 10 http://localhost:3000

Cette commande ouvre 100 connexions, s'exécute pendant 30 secondes et pipeline 10 requêtes par connexion. Un nombre plus élevé de connexions et de pipelining génère plus de charge, ce qui vous permet de trouver le point où la latence commence à augmenter.

Pour envoyer un nombre fixe de requêtes au lieu de s'exécuter pendant une durée, utilisez -a (amount) :

autocannon -c 10 -a 10000 http://localhost:3000

Cela s'arrête après 10 000 requêtes, quelle que soit la durée.

Requêtes POST, en-têtes et corps de requête

Modifiez la méthode avec -m, ajoutez des en-têtes avec -H, et passez un corps de requête avec -b. Voici un POST vers un point de terminaison JSON :

autocannon -c 50 -d 20 \
  -m POST \
  -H 'Content-Type=application/json' \
  -H 'Authorization=Bearer YOUR_TOKEN' \
  -b '{"name":"load-test","active":true}' \
  http://localhost:3000/api/users

Notez le format de l'en-tête : -H 'Clé=Valeur', et vous répétez -H pour chaque en-tête. Si votre corps est volumineux ou se trouve dans un fichier, utilisez -i pour le lire depuis le disque au lieu de l'intégrer en ligne :

autocannon -m POST -H 'Content-Type=application/json' -i payload.json http://localhost:3000/api/users

Limitation du débit du test

Par défaut, autocannon envoie les requêtes aussi vite que possible. Parfois, vous voulez un débit constant et réaliste plutôt qu'un déluge de pression maximale. -R limite le total des requêtes par seconde sur toutes les connexions :

autocannon -c 50 -R 500 -d 60 http://localhost:3000

Cela maintient le test à 500 requêtes par seconde pendant 60 secondes. C'est utile lorsque vous voulez mesurer la latence à une charge de production attendue plutôt qu'au point de rupture.

Échauffement et threads de travail

Deux drapeaux supplémentaires aident lors des exécutions plus lourdes. -W (warmup) envoie du trafic pendant un court intervalle avant qu'autocannon ne commence l'échantillonnage, afin que vos premiers chiffres ne soient pas faussés par des caches froids ou un JIT qui n'a pas eu le temps de chauffer. -w (workers) répartit la charge sur plusieurs threads de travail Node, ce qui est important lorsqu'un seul thread ne peut pas générer suffisamment de requêtes pour saturer un serveur rapide :

autocannon -c 200 -d 30 -w 4 http://localhost:3000

N'utilisez -w que lorsque vous avez confirmé que le générateur de charge lui-même est le goulot d'étranglement. Si la latence semble suspectement stable à mesure que vous augmentez -c, votre générateur est peut-être saturé, et l'ajout de threads de travail vous donne une image plus fidèle du plafond du serveur.

Lecture des résultats

Une fois l'exécution terminée, autocannon affiche un tableau de latence et une ligne de résumé. Un exemple tronqué :

Exécution d'un test de 10s @ http://localhost:3000
10 connexions

┌─────────┬──────┬──────┬───────┬──────┬─────────┬─────────┬──────────┐
│ Stat    │ 2.5% │ 50%  │ 97.5% │ 99%  │ Moy     │ Écart-type   │ Max      │
├─────────┼──────┼──────┼───────┼──────┼─────────┼─────────┼──────────┤
│ Latence │ 0 ms │ 1 ms │ 4 ms  │ 6 ms │ 1.2 ms  │ 0.9 ms  │ 24.1 ms  │
└─────────┴──────┴──────┴───────┴──────┴─────────┴─────────┴──────────┘

251k requêtes en 10.05s, 27.9 Mo lus

Voici comment le lire :

Les colonnes de centiles (2.5%, 50%, 97.5%, 99%) sont plus importantes que la moyenne. La colonne 50% est la médiane. La colonne 99% vous indique la latence que subit le 1% le plus lent de vos utilisateurs. La latence de queue est là où se cachent les vrais problèmes, alors surveillez les chiffres de 97.5% et 99%.
Moy. et Écart-type vous donnent la moyenne et la dispersion des latences. Un écart-type élevé signifie des temps de réponse inconsistants.
La ligne de résumé (« 251k requêtes en 10.05s ») est votre débit. Divisez les requêtes par les secondes pour obtenir les requêtes par seconde.

Deux drapeaux rendent la sortie plus utile. Ajoutez -l pour imprimer l'ensemble complet des centiles de latence (y compris p99.9 et au-delà), et ajoutez --renderStatusCodes pour voir une ventilation par code de statut afin de détecter une vague de 500s se cachant derrière un bon chiffre de débit :

autocannon -c 100 -d 20 -l --renderStatusCodes http://localhost:3000

Surveillez les erreurs, les timeouts et les comptes non-2xx. Un serveur peut afficher un taux de requêtes élevé tout en renvoyant discrètement des erreurs. Si non-2xx n'est pas zéro, votre chiffre de débit mesure des échecs, pas des succès.

Utilisation programmatique dans un script

autocannon expose une API Node.js, vous pouvez donc exécuter des benchmarks depuis un script et agir sur les résultats. C'est là qu'il prend tout son sens dans l'automatisation : exécutez un test, lisez les chiffres et faites échouer une build si la latence dépasse un seuil.

L'appel principal prend un objet d'options et renvoie une promesse :

const autocannon = require('autocannon')

async function run() {
  const result = await autocannon({
    url: 'http://localhost:3000',
    connections: 100,
    duration: 20,
    pipelining: 1
  })

  console.log(`Latence moyenne : ${result.latency.average} ms`)
  console.log(`Requêtes/sec : ${result.requests.average}`)
  console.log(`Non-2xx : ${result.non2xx}`)
}

run()

L'objet result contient des histogrammes pour latency, requests et throughput, chacun avec les champs average, min, max et des centiles comme p99. Il contient également les compteurs errors, timeouts et non2xx.

Pour en faire une passerelle, ajoutez une vérification qui quitte avec un code non nul lorsqu'un budget est dépassé :

const autocannon = require('autocannon')

const P99_BUDGET_MS = 250

async function run() {
  const result = await autocannon({
    url: 'http://localhost:3000/api/health',
    connections: 100,
    duration: 30
  })

  const p99 = result.latency.p99
  console.log(`Latence p99 : ${p99} ms (budget ${P99_BUDGET_MS} ms)`)

  if (p99 > P99_BUDGET_MS || result.non2xx > 0) {
    console.error('Budget de performance dépassé')
    process.exit(1)
  }
}

run()

Si vous voulez la barre de progression en direct et le tableau des résultats que l'interface CLI affiche, passez l'instance à autocannon.track :

const autocannon = require('autocannon')

const instance = autocannon({
  url: 'http://localhost:3000',
  connections: 10,
  duration: 10
}, console.log)

autocannon.track(instance, { renderProgressBar: true })

process.once('SIGINT', () => instance.stop())

Pour un scénario multi-requêtes, passez un tableau requests afin que chaque connexion parcourt plusieurs appels :

autocannon({
  url: 'http://localhost:3000',
  connections: 20,
  duration: 15,
  requests: [
    { method: 'GET', path: '/api/users' },
    { method: 'POST', path: '/api/data', body: '{"x":1}',
      headers: { 'Content-Type': 'application/json' } }
  ]
}, console.log)

autocannon vs wrk et ab

Tous trois répondent à la même question (à quelle vitesse, sous quelle charge), et le bon choix dépend de votre pile technologique.

Apache Bench (ab) est l'outil classique à un seul binaire. Il est partout et simple, mais mono-thread et daté.
wrk est rapide et peut générer une charge importante avec des scripts Lua pour des requêtes personnalisées. C'est un outil C compilé, vous l'installez donc en dehors de npm.
autocannon correspond à wrk en termes de débit pour la plupart des charges de travail et l'emporte en ergonomie si vous travaillez déjà avec Node : npm i pour l'installation, une API JavaScript pour le script, et la prise en charge du pipelining, des fichiers HAR et des scénarios par requête directement.

Si Node est votre runtime, autocannon est le choix le plus simple. Vous préférez les outils Python ? Voir comment effectuer des tests de charge sans Python. Vous voulez une option scriptable avec un large éventail de fonctionnalités ? Comparez les tests de charge k6.

Où s'intègrent les tests fonctionnels et Apidog

autocannon vous indique que votre point de terminaison sert 12 000 requêtes par seconde avec un p99 de 40 ms. Il ne vous dit pas si le point de terminaison renvoie les bonnes données. Un test de charge peut réussir avec brio alors que l'API renvoie du JSON malformé, ignore un en-tête d'authentification ou s'écarte de son contrat OpenAPI. Le débit n'est pas la justesse.

C'est la lacune que comblent les tests fonctionnels et de contrat, et c'est là que Apidog complète un outil de charge plutôt que de le remplacer. Apidog n'est pas un générateur de charge. Il exécute des scénarios de test enregistrés qui vérifient les codes de statut, les schémas de réponse et les valeurs à travers des flux en plusieurs étapes, afin que vous puissiez détecter les bugs qu'un benchmark ne peut pas voir.

Vous exécutez les deux en CI, et ils répondent à des questions différentes. Utilisez autocannon (ou wrk) pour répondre à « est-ce assez rapide sous charge ? » Utilisez l'interface CLI d'Apidog pour répondre à « est-ce correct ? » L'interface CLI d'Apidog est sans interface graphique et exécute des scénarios ou des suites de tests enregistrés depuis n'importe quelle étape de CI qui a Node :

npm install -g apidog-cli

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <idScenarioOuSuite> \
  -e <idEnvironnement> \
  -r cli,html,junit

Le drapeau -t cible un scénario, un dossier ou une suite enregistrés par leur identifiant, -e sélectionne l'environnement, et -r choisit un ou plusieurs rapporteurs (cli, html, json, junit) afin que l'exécution produise des artefacts que votre pipeline peut archiver. Pour une présentation complète, consultez comment exécuter des tests d'API depuis l'interface CLI d'Apidog, le pipeline CI/CD copier-coller, et le workflow GitHub Actions.

Un pipeline sain exécute des vérifications fonctionnelles et de contrat à chaque push (ça marche ?), puis exécute un test de charge avant la release (ça tient le coup ?). autocannon s'occupe de la deuxième question. Apidog s'occupe de la première.

FAQ

autocannon est-il précis pour les tests de charge en production ?

autocannon produit des chiffres fiables de débit et de latence pour les points de terminaison HTTP/1.1, et lorsque vous définissez un débit cible avec -R, il corrige l'omission coordonnée, une étape que de nombreux outils plus simples ignorent. Pour des résultats précis, exécutez-le depuis une machine proche de votre serveur (la latence réseau dominera sinon) et utilisez suffisamment de connexions pour saturer le point de terminaison. Exécutez-le sur un environnement de staging qui reflète la production, pas sur le serveur de développement de votre ordinateur portable.

autocannon prend-il en charge HTTP/2 ou WebSockets ?

Non. autocannon effectue des benchmarks HTTP/1.1. Pour les tests de charge HTTP/2 ou WebSocket, vous avez besoin d'un outil différent. C'est la principale contrainte à vérifier avant de le choisir.

Combien de connexions dois-je utiliser ?

Commencez avec la valeur par défaut de 10, puis augmentez -c jusqu'à ce que le nombre de requêtes par seconde cesse d'augmenter et que la latence commence à grimper. Ce point d'inflexion correspond approximativement à la capacité de votre serveur. Aller bien au-delà mesure davantage les limites de votre générateur de charge que celles de votre serveur.

Puis-je exécuter autocannon en CI ?

Oui. L'API programmatique est conçue pour cela : exécutez un benchmark, lisez result.latency.p99 et result.non2xx, et appelez process.exit(1) lorsqu'un budget est dépassé. Cela transforme un benchmark en une passerelle de réussite/échec que vous pouvez intégrer à n'importe quelle étape de CI compatible Node.

Quelle est la différence entre -a et -d ?

-d s'exécute pendant un certain nombre de secondes. -a s'exécute jusqu'à ce qu'un certain nombre de requêtes soit terminé, puis s'arrête. Utilisez -d pour un test de charge en régime permanent et -a lorsque vous voulez envoyer un nombre exact de requêtes.