Autocannon no Node.js

O Autocannon no Node.js é uma ferramenta de benchmark HTTP criada para gerar carga contra APIs e servidores web. Ela permite medir latência, taxa de requisições, erros, timeouts e throughput sem sair do ecossistema JavaScript. Para equipes que desenvolvem aplicações Node.js, isso facilita criar testes locais reproduzíveis, integrar verificações ao CI e comparar mudanças de performance antes de um deploy.

Um benchmark, porém, só é útil quando possui objetivo, ambiente controlado e critérios de aprovação. Rodar milhares de requisições contra uma rota e olhar apenas a média pode esconder caudas de latência, saturação do banco, erros intermitentes e limitações do próprio gerador de carga. Neste guia, você aprenderá a usar Autocannon pela linha de comando e pela API, configurar conexões e taxa, interpretar percentis, testar autenticação, automatizar cenários e evitar resultados enganosos.

O que é o Autocannon?

Autocannon é uma ferramenta de benchmark HTTP/1.1 escrita em Node.js, com suporte a HTTPS, pipelining, workers, taxa fixa, warm-up, corpos personalizados e uso programático. A documentação oficial está no repositório do Autocannon. Ele é especialmente conveniente para medir servidores Node.js durante o desenvolvimento, embora também possa testar aplicações escritas em outras tecnologias.

Para uma visão mais ampla de carga e cenários distribuídos, consulte Teste de Carga com k6. O Autocannon é excelente para benchmarks rápidos e integração direta com scripts Node.js; o k6 oferece recursos mais amplos para cenários, execução distribuída e análise contínua.

Instalação

npm install --save-dev autocannon

Também é possível instalar globalmente:

npm install --global autocannon

Em projetos e pipelines, prefira dependência de desenvolvimento e execução por npx. Isso fixa a versão no lockfile e reduz diferenças entre máquinas.

Primeiro benchmark

npx autocannon http://localhost:3000/health

Por padrão, a ferramenta utiliza dez conexões durante dez segundos. O relatório mostra percentis de latência, requisições por segundo, bytes por segundo, erros e total processado.

Defina uma linha de base

Antes de otimizar, execute o mesmo teste várias vezes em ambiente estável. Registre versão do código, versão do Node.js, configuração da máquina, banco utilizado e parâmetros do benchmark. Uma única execução pode ser afetada por compilação JIT, cache vazio, coleta de lixo, processos concorrentes ou inicialização tardia de conexões.

Faça primeiro um warm-up:

npx autocannon \
  --warmup [-c 5 -d 5] \
  --connections 20 \
  --duration 30 \
  http://localhost:3000/api/products

O warm-up permite que pools, caches e caminhos quentes se estabilizem antes da medição.

Conexões e concorrência

npx autocannon \
  --connections 50 \
  --duration 60 \
  http://localhost:3000/api/products

O número de conexões não representa diretamente usuários humanos. Ele representa conexões HTTP concorrentes mantidas pelo gerador. Aumente gradualmente e observe quando a latência cresce, erros aparecem ou throughput deixa de subir.

Taxa fixa

Para avaliar a aplicação sob uma taxa previsível:

npx autocannon \
  --connections 20 \
  --overallRate 500 \
  --duration 60 \
  http://localhost:3000/api/products

Uma taxa fixa ajuda a identificar o ponto em que o serviço deixa de cumprir seu SLO. Autocannon corrige a chamada coordinated omission quando a taxa não pode ser sustentada. Não desative essa correção sem compreender o impacto, porque latências ausentes podem produzir resultados otimistas.

Percentis de latência

A média não é suficiente. Observe:

• p50: experiência mediana;
• p90: cauda percebida por uma parcela relevante;
• p97.5: respostas lentas;
• p99: comportamento dos casos mais críticos;
• máximo: outliers que podem indicar pausas ou bloqueios.

Um serviço com média de 20 ms e p99 de 2 segundos possui problema de cauda. Investigue consultas lentas, contenção, pausas do garbage collector e chamadas externas.

Testando uma rota POST

npx autocannon \
  --method POST \
  --headers content-type=application/json \
  --body '{"name":"Produto","price":1990}' \
  --connections 10 \
  --duration 30 \
  http://localhost:3000/api/products

Use dados descartáveis. Não execute benchmarks destrutivos contra produção sem autorização, limites, isolamento e plano de recuperação.

Headers e autenticação

npx autocannon \
  -H authorization="Bearer $TOKEN" \
  -H accept=application/json \
  http://localhost:3000/api/account

Evite gravar tokens reais em scripts versionados. Injete segredos por variável de ambiente e use credenciais específicas de teste. Para práticas de proteção, consulte API Keys no Node.js e Gestão de Segredos no Node.js.

Uso programático

import autocannon from 'autocannon';

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

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

A API facilita transformar benchmark em uma verificação automática. O processo pode falhar quando p99, erros ou throughput ultrapassam limites definidos.

Gate de performance no CI

const limits = {
  maxP99: 250,
  maxErrors: 0,
  minRequestsPerSecond: 400
};

if (
  result.latency.p99 > limits.maxP99 ||
  result.errors > limits.maxErrors ||
  result.requests.average < limits.minRequestsPerSecond
) {
  process.exitCode = 1;
}

Não use números copiados de outro projeto. Crie limites a partir da linha de base e dos objetivos do produto. Para automação, veja Deploy com GitHub Actions.

Testando uma sequência de requisições

A opção requests permite representar uma sequência:

const result = await autocannon({
  url: 'http://localhost:3000',
  connections: 10,
  duration: 30,
  requests: [
    { method: 'GET', path: '/api/products' },
    { method: 'GET', path: '/api/categories' },
    { method: 'GET', path: '/health' }
  ]
});

Esse recurso é útil para misturar rotas, mas ainda não representa comportamento completo de usuários. Para cenários complexos, duração longa e chegada controlada, o k6 pode ser mais apropriado.

Workers

npx autocannon \
  --workers 4 \
  --connections 80 \
  --duration 60 \
  http://localhost:3000/api/products

Workers distribuem o gerador por threads. Observe o consumo da máquina de carga. Se o próprio Autocannon atingir o limite de CPU, ele pode deixar de gerar tráfego suficiente e o benchmark passa a medir o cliente, não o servidor.

Pipelining

HTTP pipelining envia múltiplas requisições pela mesma conexão sem esperar cada resposta:

npx autocannon \
  --connections 10 \
  --pipelining 10 \
  http://localhost:3000/api/products

Use apenas quando isso representar o cliente real. Pipelining pode gerar uma carga muito diferente de navegadores, aplicações móveis ou proxies comuns.

Timeout e bailout

npx autocannon \
  --timeout 5 \
  --bailout 100 \
  --duration 120 \
  http://localhost:3000/api/products

O timeout impede conexões presas por tempo excessivo. O bailout encerra o teste após quantidade definida de falhas, evitando continuar atacando um ambiente claramente degradado.

Validação de resposta

Não considere apenas status. Uma aplicação pode responder 200 com conteúdo incorreto. A API oferece verifyBody e a CLI possui expectBody, embora validar cada resposta aumente o custo do gerador.

const result = await autocannon({
  url: 'http://localhost:3000/health',
  verifyBody(body) {
    const parsed = JSON.parse(body);
    return parsed.status === 'ok';
  }
});

JSON para relatórios

npx autocannon \
  --json \
  --duration 30 \
  http://localhost:3000/api/products \
  > benchmark.ndjson

Armazene resultados como artefatos do pipeline, mas evite comparar máquinas diferentes como se fossem equivalentes.

Monitore o servidor durante o teste

Correlacione o benchmark com CPU, memória, event loop, conexões do banco, cache, filas e logs. O módulo oficial Performance Hooks do Node.js ajuda a observar métricas internas. Consulte também Performance Hooks no Node.js e Métricas Prometheus no Node.js.

Ambiente de teste

• Use máquina de carga separada para testes importantes.
• Fixe versões e configuração.
• Desative processos concorrentes desnecessários.
• Garanta dados representativos.
• Aqueça caches quando esse for o cenário real.
• Execute também com cache frio quando relevante.
• Repita o teste várias vezes.
• Compare distribuições, não apenas uma média.

Erros comuns

• Testar localhost e generalizar: rede real possui latência e limites diferentes.
• Ignorar erros HTTP: throughput alto com respostas 500 não é sucesso.
• Gerador saturado: a ferramenta não consegue produzir a carga desejada.
• Teste curto: não revela vazamento, aquecimento ou degradação progressiva.
• Dados irreais: consultas simples não representam produção.
• Sem warm-up: inicialização contamina o resultado.
• Comparar ambientes distintos: conclusão fica inválida.
• Executar em produção sem controle: risco de indisponibilidade.

Autocannon, k6 ou Testcontainers?

Use Autocannon para benchmarks HTTP rápidos e scripts integrados ao Node.js. Use k6 para cenários de carga avançados, execução distribuída e métricas de desempenho contínuas. Use Testcontainers no Node.js para subir dependências reais em testes de integração; ele não substitui um gerador de carga, mas cria ambientes reproduzíveis.

Conclusão

O Autocannon no Node.js oferece uma maneira direta de medir APIs, comparar alterações e detectar regressões. O valor da ferramenta não está apenas em gerar muitas requisições, mas em executar cenários controlados, observar percentis, validar respostas e correlacionar resultados com métricas do servidor.

Comece com uma linha de base, aumente carga gradualmente e defina critérios ligados aos objetivos do serviço. Com warm-up, taxa controlada, repetições e automação no CI, Autocannon se torna uma ferramenta confiável para decisões de performance, e não apenas um comando que produz números impressionantes.