Autocannon no Node.js

Autocannon é uma ferramenta de benchmark HTTP/1.1 escrita em Node.js. Ela gera carga concorrente contra APIs HTTP ou HTTPS e apresenta métricas de latência, requisições por segundo, throughput, erros, timeouts e códigos de status. É útil para comparar mudanças locais, encontrar limites de uma rota e validar se uma otimização realmente melhorou o comportamento.

Benchmark não é o mesmo que teste funcional nem teste de capacidade completo. O resultado depende de hardware, rede, banco, aquecimento, carga gerada e configuração do cliente. Use Autocannon como instrumento controlado, não como número absoluto de marketing.

Instalação

npm install -D autocannon

Ou globalmente:

npm install -g autocannon

Em projetos e CI, prefira dependência local fixada no lockfile.

Primeiro benchmark

npx autocannon -c 20 -d 30 http://127.0.0.1:3000/health

-c define conexões concorrentes e -d duração em segundos. Comece com carga pequena e aumente gradualmente.

Aquecimento

O início da aplicação pode envolver JIT, criação de pools, carregamento de módulos e cache frio. Use warmup:

npx autocannon \
  --warmup [ -c 5 -d 10 ] \
  -c 50 \
  -d 60 \
  http://127.0.0.1:3000/api/items

Sem aquecimento, resultados curtos podem medir inicialização em vez do estado estável.

Entendendo latência

Autocannon mostra percentis como p50, p97.5, p99 e máximos. A média sozinha esconde caudas.

• p50: metade das requisições foi mais rápida;
• p90: 90% ficou abaixo desse valor;
• p99: mostra as requisições muito lentas;
• max: pior valor observado.

Uma API com média de 20 ms e p99 de 900 ms pode oferecer experiência ruim em picos.

Requisições por segundo

Req/Sec indica volume processado. Compare junto com erros e latência. Aumentar throughput às custas de timeouts não é melhoria.

POST com JSON

npx autocannon \
  -c 25 \
  -d 30 \
  -m POST \
  -H 'content-type=application/json' \
  -b '{"name":"Ana","email":"ana@example.com"}' \
  http://127.0.0.1:3000/users

Use dados de teste. Uma rota de criação pode acumular registros e alterar o resultado ao longo da execução.

Headers e autenticação

npx autocannon \
  -H 'authorization=Bearer TOKEN_DE_TESTE' \
  -H 'accept=application/json' \
  -c 20 -d 30 \
  http://127.0.0.1:3000/private

Nunca grave token de produção no script ou log do CI. Gere credencial temporária em ambiente isolado.

Taxa fixa

Para enviar uma taxa total:

npx autocannon \
  -c 50 \
  -R 1000 \
  -d 60 \
  http://127.0.0.1:3000/api

overallRate ajuda a simular chegada constante. Se o servidor não acompanha, Autocannon corrige estatísticas para coordinated omission por padrão. Não desative essa correção sem entender o problema.

Coordinated omission

Quando o gerador espera a resposta antes de enviar a próxima requisição, períodos lentos reduzem a quantidade de amostras justamente durante o problema. Isso faz a latência parecer melhor. Testes com taxa definida e correção capturam requisições que deveriam ter sido enviadas.

Pipelining

npx autocannon -c 10 -p 10 -d 30 http://127.0.0.1:3000/

HTTP pipelining envia várias requisições por conexão sem esperar respostas. Muitos clientes reais não usam esse padrão. Mantenha pipelining: 1 quando quiser representar tráfego comum.

Workers

npx autocannon -w 4 -c 100 -d 60 http://127.0.0.1:3000/

Workers usam threads para gerar mais carga. Confirme que a máquina geradora não é o gargalo. Monitore CPU do Autocannon e do servidor separadamente.

Benchmark na mesma máquina

Executar gerador e servidor juntos cria competição por CPU. Isso é útil para comparação rápida, mas não mede capacidade real. Para testes maiores, use máquina separada ou limite recursos de forma consistente.

API programática

import autocannon from 'autocannon';

const result = await autocannon({
  url: 'http://127.0.0.1:3000/api/items',
  connections: 25,
  duration: 30,
  pipelining: 1,
  headers: {
    accept: 'application/json',
  },
});

console.log({
  requestsPerSecond: result.requests.average,
  latencyP99: result.latency.p99,
  errors: result.errors,
  timeouts: result.timeouts,
  non2xx: result.non2xx,
});

A API permite integrar limites e relatórios ao CI.

Iniciando a aplicação automaticamente

A CLI pode iniciar um comando e esperar a porta:

npx autocannon --on-port /api/items -- node dist/server.js

Também é possível criar um script que inicia o processo, espera readiness, executa carga e encerra com sinais.

Warmup programático

Execute uma rodada curta e descarte o resultado antes da medição:

await autocannon({
  url,
  connections: 5,
  duration: 10,
});

const result = await autocannon({
  url,
  connections: 50,
  duration: 60,
});

Sequência de requisições

A opção requests permite ciclo:

const result = await autocannon({
  url: 'http://127.0.0.1:3000',
  connections: 10,
  duration: 30,
  requests: [
    { method: 'POST', path: '/sessions', body: '{"user":"test"}' },
    { method: 'GET', path: '/profile' },
  ],
});

Para fluxos com token dinâmico, use contexto, onResponse e setupRequest. Cuidado para o script de carga não virar o gargalo.

Verificando resposta

expectBody ou verifyBody detecta respostas incorretas:

const result = await autocannon({
  url,
  connections: 10,
  duration: 20,
  verifyBody(body) {
    return body.includes('"status":"ok"');
  },
  bailout: 10,
});

Validar corpo aumenta custo do gerador. Use verificações simples e monitore mismatches.

Bailout

Interrompa após erros:

npx autocannon -B 100 -c 50 -d 60 http://127.0.0.1:3000/

Isso protege o ambiente e evita continuar uma execução claramente inválida.

JSON para CI

npx autocannon -j -c 20 -d 30 http://127.0.0.1:3000/ > result.ndjson

Na API, salve o objeto final em JSON. Compare métricas com uma baseline e tolerância, não com valores rígidos frágeis.

Critérios de aprovação

if (result.errors > 0 || result.non2xx > 0) {
  throw new Error('Benchmark apresentou erros');
}

if (result.latency.p99 > 250) {
  throw new Error(`p99 acima do limite: ${result.latency.p99}ms`);
}

Benchmarks em runners compartilhados variam. Reserve regressões claras para bloquear PRs; execute medições precisas em ambiente dedicado.

Cenários de carga

Teste níveis:

• smoke: carga pequena e curta;
• baseline: tráfego esperado;
• stress: aumento até degradação;
• spike: salto repentino;
• soak: duração longa;
• breakpoint: limite máximo.

Autocannon é excelente para benchmarks curtos e HTTP/1.1. Cenários distribuídos e jornadas complexas podem exigir k6.

Banco de dados

Uma rota pode parecer rápida com dados pequenos e cache quente. Use volume representativo, índices reais e pool configurado. Monitore queries, conexões e locks durante a carga.

Cache

Separe teste de cache frio e quente. Limpar cache antes de cada execução muda o cenário. Registre explicitamente o estado.

Observabilidade durante o benchmark

Correlacione:

• CPU e memória;
• event loop lag;
• GC;
• pool de banco;
• latência externa;
• erros;
• p95 e p99;
• throughput.

Sem telemetria, você sabe que ficou lento, mas não por quê.

Limitações

Autocannon é escrito em JavaScript e pode consumir muita CPU. Em cargas extremas, a máquina geradora satura antes do alvo. Compare CPU e considere wrk2 ou teste distribuído.

A ferramenta é focada em HTTP/1.1. Não assuma que representa HTTP/2, WebSocket ou comportamento completo de navegador.

Segurança

Execute apenas contra ambientes autorizados. Um benchmark pode causar indisponibilidade, custo e perda de dados. Use dados descartáveis, rate limit e janela combinada.

Fluxo recomendado

Defina hipótese, aqueça, execute carga controlada, observe percentis e erros, repita várias vezes e compare medianas. Combine com event loop no Node.js, métricas em Prometheus no Node.js, profiling em Pyroscope no Node.js e CI em GitHub Actions.

Consulte o repositório oficial do Autocannon e a documentação oficial de performance hooks do Node.js.