Você escreveu um endpoint HTTP. Ele funciona quando você o acessa uma vez do Postman. Mas o que acontece quando 200 clientes o acessam ao mesmo tempo? Você precisa de números: requisições por segundo, percentis de latência e quantas respostas retornaram com um status diferente de 2xx. O autocannon fornece esses números direto do seu terminal em cerca de dez segundos.
autocannon é uma ferramenta de benchmark HTTP/1.1 escrita em Node.js. Ele dispara um fluxo controlado de requisições para uma URL e reporta a taxa de transferência e a latência. Este guia te levará pela instalação, uma execução básica, cada flag que você realmente usará, como ler a saída e como usar o autocannon a partir de um script Node. Ele também traça uma linha clara entre o que um teste de carga te diz e o que ele não diz, para que você saiba quando usar um teste funcional e de contrato em vez disso.
O que é o autocannon
autocannon abre um número fixo de conexões concorrentes para uma URL e continua enviando requisições por uma duração definida (ou uma contagem de requisições definida). Enquanto executa, ele coleta amostras de latência e conta as respostas. Ao terminar, ele imprime uma tabela de percentis de latência e um resumo do total de requisições e bytes lidos.
Ele mede uma coisa: quanta carga seu servidor suporta e quão rápido ele responde sob essa carga. Ele não verifica se o corpo da resposta está correto, se sua API corresponde à sua especificação OpenAPI, ou se um fluxo de trabalho de várias etapas retorna os dados corretos em cada etapa. Mantenha essa distinção em mente. Isso molda onde o autocannon se encaixa na sua pilha de testes, abordado mais adiante.
Se você já usou wrk ou Apache Bench, o autocannon preenche o mesmo espaço com uma instalação nativa do Node e uma API programática que você pode chamar a partir do JavaScript.
Instalação
autocannon é distribuído como um pacote npm. Instale-o globalmente para ter o autocannon comando em qualquer lugar:
npm i autocannon -g
Você precisa ter o Node.js instalado primeiro. Se preferir não instalar globalmente, execute-o sob demanda com npx:
npx autocannon http://localhost:3000
Ou adicione-o a um projeto como uma dependência de desenvolvimento quando planejar criar scripts com ele:
npm i autocannon --save-dev
Verifique a instalação:
autocannon --version
Execução básica
A forma mais simples é o comando mais uma URL. Isso executa o benchmark padrão: 10 conexões por 10 segundos.
autocannon http://localhost:3000
Ajuste os parâmetros com três flags que você usará constantemente. -c define o número de conexões concorrentes, -d define a duração em segundos e -p define o pipelining (quantas requisições cada conexão envia antes de esperar por uma resposta).
autocannon -c 100 -d 30 -p 10 http://localhost:3000
Esse comando abre 100 conexões, executa por 30 segundos e faz pipelining de 10 requisições por conexão. Maiores contagens de conexões e pipelining aumentam a carga, que é como você encontra o ponto onde a latência começa a subir.
Para enviar um número fixo de requisições em vez de executar por uma duração, use -a (quantidade):
autocannon -c 10 -a 10000 http://localhost:3000
Isso para após 10.000 requisições, independentemente do tempo.
Requisições POST, cabeçalhos e um corpo
Altere o método com -m, adicione cabeçalhos com -H e passe um corpo de requisição com -b. Aqui está um POST para um endpoint 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
Observe o formato do cabeçalho: -H 'Chave=Valor', e você repete -H para cada cabeçalho. Se o seu corpo for grande ou estiver em um arquivo, use -i para lê-lo do disco em vez de incorporá-lo:
autocannon -m POST -H 'Content-Type=application/json' -i payload.json http://localhost:3000/api/users
Limitação de taxa do teste
Por padrão, o autocannon envia o mais rápido que pode. Às vezes, você quer uma taxa constante e realista, em vez de uma inundação de pressão máxima. -R limita o total de requisições por segundo em todas as conexões:
autocannon -c 50 -R 500 -d 60 http://localhost:3000
Isso mantém o teste em 500 requisições por segundo por 60 segundos. Isso é útil quando você deseja medir a latência em uma carga de produção esperada, em vez de no ponto de ruptura.
Aquecimento e threads de worker
Duas outras flags ajudam em execuções mais pesadas. -W (aquecimento) envia tráfego por um curto intervalo antes que o autocannon comece a coletar amostras, para que seus primeiros números não sejam distorcidos por caches frios ou um JIT que ainda não aqueceu. -w (workers) distribui a carga por várias threads de worker do Node, o que importa quando uma única thread não consegue gerar requisições suficientes para saturar um servidor rápido:
autocannon -c 200 -d 30 -w 4 http://localhost:3000
Use -w apenas quando você tiver confirmado que o próprio gerador de carga é o gargalo. Se a latência parecer suspeitosamente estável ao aumentar -c, seu gerador pode estar no limite, e adicionar workers lhe dará uma imagem mais verdadeira do teto do servidor.
Lendo os resultados
Quando uma execução termina, o autocannon imprime uma tabela de latência e uma linha de resumo. Um exemplo abreviado:
Running 10s test @ http://localhost:3000
10 connections
┌─────────┬──────┬──────┬───────┬──────┬─────────┬─────────┬──────────┐
│ Stat │ 2.5% │ 50% │ 97.5% │ 99% │ Avg │ Stdev │ Max │
├─────────┼──────┼──────┼───────┼──────┼─────────┼─────────┼──────────┤
│ Latency │ 0 ms │ 1 ms │ 4 ms │ 6 ms │ 1.2 ms │ 0.9 ms │ 24.1 ms │
└─────────┴──────┴──────┴───────┴──────┴─────────┴─────────┴──────────┘
251k requests in 10.05s, 27.9 MB read
Veja como interpretá-lo:
- As colunas de percentil (2.5%, 50%, 97.5%, 99%) importam mais do que a média. A coluna de 50% é a mediana. A coluna de 99% indica a latência que o seu 1% de usuários mais lentos experimenta. A latência de cauda é onde os problemas reais se escondem, então observe os números de 97.5% e 99%.
- Média (Avg) e Desvio Padrão (Stdev) fornecem a média e a dispersão das latências. Um alto desvio padrão significa tempos de resposta inconsistentes.
- A linha de resumo ("251k requests in 10.05s") é a sua taxa de transferência. Divida as requisições pelos segundos para obter as requisições por segundo.
Duas flags tornam a saída mais útil. Adicione -l para imprimir o conjunto completo de percentis de latência (incluindo p99.9 e além), e adicione --renderStatusCodes para ver um detalhamento por código de status, para que você possa identificar uma onda de 500s escondida atrás de um bom número de taxa de transferência:
autocannon -c 100 -d 20 -l --renderStatusCodes http://localhost:3000
Observe as contagens de erros, timeouts e status não-2xx. Um servidor pode apresentar uma alta taxa de requisições enquanto silenciosamente retorna erros. Se a contagem de não-2xx não for zero, seu número de taxa de transferência está medindo falhas, não sucesso.
Uso programático em um script
autocannon expõe uma API Node.js, para que você possa executar benchmarks a partir de um script e agir com base nos resultados. É aqui que ele mostra seu valor na automação: execute um teste, leia os números e faça a build falhar se a latência ultrapassar um limite.
const autocannon = require('autocannon')
async function run() {
const result = await autocannon({
url: 'http://localhost:3000',
connections: 100,
duration: 20,
pipelining: 1
})
console.log(`Avg latency: ${result.latency.average} ms`)
console.log(`Req/sec: ${result.requests.average}`)
console.log(`Non-2xx: ${result.non2xx}`)
}
run()
O objeto result contém histogramas para latency (latência), requests (requisições) e throughput (taxa de transferência), cada um com campos de average (média), min (mínimo), max (máximo) e percentis como p99. Ele também carrega as contagens de errors (erros), timeouts (tempos limite) e non2xx (não-2xx).
Para transformar isso em um "portão" de qualidade, adicione uma verificação que sai com um código diferente de zero quando um orçamento de desempenho é excedido:
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(`p99 latency: ${p99} ms (budget ${P99_BUDGET_MS} ms)`)
if (p99 > P99_BUDGET_MS || result.non2xx > 0) {
console.error('Performance budget exceeded')
process.exit(1)
}
}
run()
Se você quiser a barra de progresso em tempo real e a tabela de resultados que o CLI mostra, passe a instância para 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())
Para um cenário de múltiplas requisições, passe um array requests para que cada conexão passe por várias chamadas:
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 e ab
Todos os três respondem à mesma pergunta (quão rápido, sob quanta carga), e a escolha certa depende da sua pilha de tecnologia.
- Apache Bench (ab) é a ferramenta clássica de binário único. Está em todo lugar e é simples, mas é single-threaded e datada.
- wrk é rápido e pode gerar cargas pesadas com scripting Lua para requisições personalizadas. É uma ferramenta compilada em C, então você a instala fora do npm.
- autocannon se iguala ao wrk em taxa de transferência para a maioria das cargas de trabalho e ganha em ergonomia se você já trabalha com Node:
npm ipara instalar, uma API JavaScript para scripts e suporte para pipelining, arquivos HAR e cenários por requisição prontos para uso.
Se Node é o seu ambiente de execução, autocannon é a escolha de baixa fricção. Prefere ferramentas Python? Veja como fazer teste de carga sem Python. Quer uma opção scriptável com um grande conjunto de recursos? Compare o teste de carga k6.
Onde o teste funcional e o Apidog se encaixam
autocannon te diz que seu endpoint atende 12.000 requisições por segundo com um p99 de 40 ms. Ele não te diz se o endpoint retorna os dados corretos. Um teste de carga pode ser aprovado com louvor enquanto a API retorna JSON malformado, ignora um cabeçalho de autenticação ou se desvia de seu contrato OpenAPI. Taxa de transferência não é correção.
Essa é a lacuna que o teste funcional e de contrato preenche, e é onde o Apidog complementa uma ferramenta de carga em vez de substituí-la. O Apidog não é um gerador de carga. Ele executa cenários de teste salvos que validam códigos de status, esquemas de resposta e valores em fluxos de várias etapas, para que você pegue os bugs que um benchmark não consegue ver.
Você executa ambos na CI, e eles respondem a perguntas diferentes. Use o autocannon (ou wrk) para responder "é rápido o suficiente sob carga?" Use o Apidog CLI para responder "está correto?" O Apidog CLI é headless e executa cenários ou suítes de teste salvos de qualquer etapa da CI que tenha Node:
npm install -g apidog-cli
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t <scenarioOrSuiteId> \
-e <environmentId> \
-r cli,html,junit
A flag -t direciona para um cenário, pasta ou suíte salvo por id, -e seleciona o ambiente, e -r escolhe um ou mais relatórios (cli, html, json, junit) para que a execução produza artefatos que sua pipeline possa arquivar. Para um guia completo, veja como executar testes de API a partir do Apidog CLI, a pipeline de CI/CD de copiar e colar, e o workflow do GitHub Actions.
Uma pipeline saudável executa verificações funcionais e de contrato em cada push (funciona?), e então executa um teste de carga antes do lançamento (suporta a carga?). O autocannon responde à segunda pergunta. O Apidog responde à primeira.
Perguntas Frequentes
O autocannon é preciso para testes de carga em produção?
autocannon produz números confiáveis de taxa de transferência e latência para endpoints HTTP/1.1, e quando você define uma taxa alvo com -R, ele corrige a omissão coordenada, uma etapa que muitas ferramentas mais simples ignoram. Para resultados precisos, execute-o de uma máquina próxima ao seu servidor (a latência de rede domina de outra forma) e use conexões suficientes para saturar o endpoint. Execute-o contra um ambiente de staging que espelhe a produção, não contra o servidor de desenvolvimento do seu laptop.
O autocannon suporta HTTP/2 ou WebSockets?
Não. O autocannon faz benchmark de HTTP/1.1. Para testes de carga de HTTP/2 ou WebSocket, você precisa de uma ferramenta diferente. Esta é a principal restrição a ser verificada antes de escolhê-lo.
Quantas conexões devo usar?
Comece com o padrão de 10, depois aumente -c até que as requisições por segundo parem de subir e a latência comece a aumentar. Esse ponto de inflexão é aproximadamente a capacidade do seu servidor. Forçar muito além disso mede mais os limites do seu gerador de carga do que os do seu servidor.
Posso executar o autocannon na CI?
Sim. A API programática foi criada para isso: execute um benchmark, leia result.latency.p99 e result.non2xx, e chame process.exit(1) quando um orçamento for excedido. Isso transforma um benchmark em um "portão" de aprovação/reprovação que você pode integrar em qualquer etapa da CI compatível com Node.
Qual a diferença entre -a e -d?
-d executa por um número de segundos. -a executa até que um número de requisições seja concluído e então para. Use -d para um teste de carga em estado estável e -a quando você quiser enviar uma contagem exata de requisições.