Depurar HTTP com curl: saída detalhada, análise de tempos e forçar a conexão

Objetivo

Responder a três perguntas com uma única ferramenta e sem navegador: o que o servidor recebeu e devolveu, quanto tempo levou cada fase e se um backend específico se comporta da mesma forma que o servidor para o qual o nome é resolvido.

Pré-requisitos

O curl, a URL e os cabeçalhos ou credenciais de que a requisição precisar. Um método seguro para alvos em produção (-I para HEAD, ou GET em endpoints somente de leitura).

Passos

1. Ver a conversa: curl -v URL imprime no stderr os cabeçalhos da requisição e da resposta, além dos detalhes da conexão; --trace-ascii - despeja também os corpos, e --trace-time adiciona um carimbo de tempo a cada linha. O manual avisa que os traces podem conter credenciais, por isso remova-as antes de compartilhar.
2. Separar cabeçalhos e corpo: -D - grava os cabeçalhos da resposta na saída padrão, -o /dev/null descarta o corpo e -sS oculta a barra de progresso, mas mantém as mensagens de erro.
3. Localizar a fase lenta com -w (--write-out). O manual define as variáveis de tempo como segundos contados desde o início: time_namelookup (resolução de nome concluída), time_connect (TCP conectado), time_appconnect (handshake TLS concluído), time_pretransfer, time_starttransfer (primeiro byte recebido, o que inclui o tempo de processamento do servidor) e time_total. Exemplo: curl -sS -o /dev/null -w 'dns %{time_namelookup} tcp %{time_connect} tls %{time_appconnect} ttfb %{time_starttransfer} total %{time_total} code %{response_code}\n' URL. Subtraia valores vizinhos para obter a duração de cada fase e repita a medição várias vezes, pois a primeira execução inclui caches frios.
4. Alcançar um único servidor atrás de um load balancer, ou testar antes de uma mudança de DNS: --resolve host:port:addr fornece o endereço para aquele host e porta (o manual o descreve como um /etc/hosts na linha de comando), de modo que SNI, validação do certificado e o cabeçalho Host continuam corretos. --connect-to HOST1:PORT1:HOST2:PORT2 redireciona apenas a conexão TCP e deixa inalterados os nomes usados no TLS e na requisição.
5. Tornar as falhas visíveis em scripts: --fail-with-body retorna o código de saída 22 para status 400 ou superior e ainda assim salva o corpo (-f o descarta); --max-time limita a duração da operação inteira; --retry N repete a requisição em caso de erros transitórios.
6. Fixar o que está sendo comparado: --http1.1 ou --http2 seleciona o protocolo; --compressed solicita uma resposta comprimida com os algoritmos que o curl suporta e a descomprime; --json envia um corpo JSON com os cabeçalhos correspondentes.

Resultado esperado

Um comando reproduzível cuja saída mostra a requisição exata, o status e os cabeçalhos da resposta e uma análise de tempos que aponta para DNS, TCP, TLS, processamento no servidor ou transferência.

Limites e base de verificação

A semântica das opções segue o manual citado; várias opções indicam a versão do curl em que foram introduzidas, portanto verifique a versão instalada. Os tempos refletem a perspectiva de um único cliente, incluindo o cache do próprio resolvedor e o caminho de rede dele; não são medições do lado do servidor. Nenhum valor numérico é afirmado.