Analizzare le Richieste HTTP Direttamente nel Terminale con httptap

Quando un servizio esterno o un microservizio interno inizia improvvisamente a rallentare, le mani raggiungono naturalmente la buona vecchia curl. Ma curl standard emette solo il corpo della risposta, e per estrarre i tempi delle fasi di connessione, devi costruire un modello mostruoso con una dozzina di variabili tramite il flag -w. Oppure apri un browser, vai nella scheda Network di DevTools e ammiri il grafico waterfall. Su una console di server remoto, non puoi aprire un browser, e scavare nell'output grezzo è una seccatura.

Di recente mi sono imbattuto in httptap. È un comodo strumento Python che scompone qualsiasi richiesta HTTP nelle sue fasi componenti: DNS, handshake TCP, negoziazione TLS, time to first byte (TTFB) e trasferimento del corpo della risposta. Tutto questo viene visualizzato come un chiaro grafico waterfall direttamente nella console.

---

Cosa C'è Sotto il Cofano e Perché Ti Serve

Lo strumento è costruito in Python usando httpx, httpcore, dnspython e la libreria Rich per il rendering dell'interfaccia. Non misura solo il tempo totale di risposta—si aggancia al tracing dello stack di rete e mostra esattamente in quale fase una richiesta si è bloccata.

Se hai mai usato il progetto httpstat, l'idea ti risulterà familiare. Ma httptap ha diverse differenze chiave:

• Può tracciare le catene di redirect e misurare i tempi di ogni passaggio separatamente, mostrando una tabella riepilogativa.
• Supporta controlli di budget di latenza (SLO) con codici di uscita leggibili.
• Ispeziona i certificati TLS: riporta hostname (CN), algoritmo cipher, versione del protocollo e giorni alla scadenza.
• Esporta JSON strutturato dettagliato con tutte le metriche per l'automazione.
• Capisce i flag di curl (-X, -L, -H, -k, -x), quindi non devi ritrainare le dita.

---

Come Installare ed Eseguire

Il modo più veloce per installare su macOS o Linux è tramite Homebrew:

brew install httptap

Se preferisci gli strumenti Python, pip o uv funzioneranno:

uv pip install httptap
# или
pip install httptap

C'è anche un'immagine Docker pronta all'uso nel registro GitHub Packages:

docker run --rm ghcr.io/ozeranskii/httptap:latest https://example.com

L'uso base è semplice:

httptap https://httpbin.io/get

Lo strumento effettuerà la richiesta e mostrerà una tabella ordinata con i tempi per ogni passaggio, codice di stato e info di rete (inclusa la versione del protocollo HTTP/2 e la famiglia di indirizzi IPv4/IPv6).

---

Cosa Sa Fare lo Strumento in Pratica

Lavorare con Qualsiasi Metodo HTTP e Corpo della Richiesta

Lo strumento invia JSON o XML senza problemi. Se passi il flag --data senza specificare esplicitamente un metodo, lo strumento passerà automaticamente a POST, imitando il comportamento di curl:

httptap https://httpbin.io/post --data '{"status": "testing", "source": "httptap"}'

Se i dati sono in un file, puoi passare il percorso tramite la sintassi @:

httptap https://httpbin.io/post --data @payload.json

Per altri metodi, c'è il familiare flag --method (o -X):

httptap https://httpbin.io/put --method PUT --data '{"key": "value"}'

Tracciare le Catene di Redirect

Pochi strumenti riescono a mostrare correttamente quanto tempo richiede una serie di risposte 301 e 302. Qui basta aggiungere il flag --follow (o -L):

httptap --follow https://httpbin.io/redirect/2

L'output includerà un'analisi dettagliata per ogni host intermedio e una riga finale con il tempo totale.

Controllare i Budget di Latenza in CI

Una delle funzionalità più utili del progetto è il flag --slo. Trasforma lo strumento in uno strumento di smoke test e gate per le pipeline di build:

httptap --slo total=500,ttfb=200 https://api.example.com/health

Se il servizio target risponde con stato 200 ma TTFB supera i 200 millisecondi o il tempo totale supera i 500 millisecondi, lo strumento restituirà il codice di uscita 4. Se si verifica un errore di rete, restituisce il codice 75 (EX_TEMPFAIL secondo lo standard BSD sysexits).

Grazie alla separazione del codice, puoi configurare uno script di deployment per distinguere tra errori di rete e degrado delle prestazioni:

httptap --slo total=1500,tls=200 https://staging.example.com/
case $? in
  0) echo "Сервис уложился в нормативы" ;;
  4) echo "Нарушен SLO по времени ответа"; exit 1 ;;
  75) echo "Временный сетевой сбой, повторяем проверку" ;;
esac

Scripting e Output Compatto

Per automazione e job cron, l'output grafico di Rich potrebbe essere eccessivo. Per questi scenari sono disponibili due modalità:

1. Modalità linea compatta --compact per i log:

   httptap --compact https://httpbin.io/get
   

2. Stream di testo delle metriche --metrics-only:

   httptap --metrics-only https://httpbin.io/get
   

   Otterrai una singola riga di ritorno come:

   Step 1: dns=30.1 connect=97.3 tls=199.0 ttfb=472.2 total=476.0 status=200 bytes=389 ip=44.211.11.205 family=IPv4 tls_version=TLSv1.2 proxy=direct
   

3. Esportazione JSON tramite --json out/report.json, dove vengono salvati tempi, header, parametri TLS e indirizzi IP.

---

Resolver Personalizzati ed Estensibilità

Se stai scrivendo utility Python interne, httptap può essere usato come libreria. L'architettura è costruita sui protocolli (typing.Protocol), quindi i componenti sono facili da sostituire. Ad esempio, puoi sovrascrivere il resolver DNS per testare la risposta di un IP specifico senza modificare /etc/hosts:

from httptap import HTTPTapAnalyzer, SystemDNSResolver


class StaticDNS(SystemDNSResolver):
    def resolve(self, host, port, timeout):
        return "93.184.216.34", "IPv4", 0.05


analyzer = HTTPTapAnalyzer(dns_resolver=StaticDNS())
steps = analyzer.analyze_url("https://example.com")
for step in steps:
    print(f"TTFB: {step.timing.ttfb_ms:.2f} ms")

---

Lo strumento si è rivelato compatto, veloce e focalizzato su un compito specifico. Colma piacevolmente il divario tra la pura curl -w e i profiler grafici pesanti.

L'utility sarà utile per gli ingegneri operativi per la diagnosi rapida di endpoint lenti sui server, per gli sviluppatori backend per misurare le latenze delle API esterne, e per i team QA per controllare gli SLO direttamente nelle pipeline. Prova a installarlo localmente e a sostituire la tua solita curl -I per un paio di giorni. La differenza in termini di chiarezza è immediatamente evidente.