The Problem

httptap solves a specific diagnostic gap: when an HTTP request is slow, you need to know where the time went. Standard tools like curl report total time but obscure the breakdown between DNS resolution, TCP connect, TLS handshake, server wait, and body transfer. This makes performance regression analysis guesswork.

What This Does

httptap is a Python CLI that intercepts an HTTP request and measures each phase independently. It renders results as a Rich-powered waterfall timeline, a compact summary, or metrics-only output suitable for scripting. The httptap/ package contains the core logic, with httptap/cli.py as the entry point and httptap/http_client.py handling the actual request execution.

The project also includes SLO threshold checking (httptap/slo.py), JSON export (httptap/exporter.py), and a TLS inspector (httptap/tls_inspector.py). Tests are comprehensive (21 files), and the project ships with GitHub Actions CI, a Dockerfile, and MkDocs documentation.

How It Is Wired

Execution starts at main in httptap/cli.py:520, which reaches 65 functions. The CLI parses arguments, then calls execute in httptap/request_executor.py:63, which reaches 50 functions and is the central orchestration point. execute calls make_request, which builds TimingMetrics, NetworkInfo, and ResponseInfo objects—these three data structures are called from 62, 48, and 45 places respectively, making them the highest-blast-radius types in the codebase.

The request path touches the filesystem via read_request_data -> _load_data_from_source (reading input files) and _export_results -> export_json -> _write_json_file (writing output). Two functions make outbound network calls. The module graph shows httptap/models as a hub with 27 dependents—changing it ripples widely. httptap/constants and httptap/utils are stable leaves (0 instability), while httptap/__init__ and httptap/http_client are more volatile.

File-by-file: httptap/cli.py owns argument parsing and orchestration, httptap/http_client.py owns the HTTP request and timing capture, httptap/analyzer.py handles redirects and SLO evaluation, httptap/render.py and httptap/visualizer.py produce output, and httptap/formatters.py handles metrics formatting.

How To Use It

Setup: The project uses pyproject.toml with uv.lock present. Install with:

git clone https://github.com/moses-y/httptap
cd httptap
uv sync

Running it:

httptap https://example.com
httptap https://example.com --format metrics
httptap https://example.com --export results.json

Configuration: No environment variables are required. The SLO spec is passed via CLI arguments, not a config file.

Real-World Use

For a production API endpoint that regressed from 200ms to 900ms, run:

httptap https://api.example.com/v1/orders --format timeline

The waterfall will show whether the regression is in DNS (infrastructure), TLS handshake (certificate chain), server wait (backend), or transfer (network). Export to JSON for CI-based baseline comparison:

httptap https://api.example.com/v1/orders --format metrics --slo "dns<50,connect<100,tls<100,wait<300"

Code Health & Issues

Static analysis found 11 findings (2 high, 9 medium). High severity: duplicated code blocks—19 repeated 6-line blocks across 15 files, suggesting extraction opportunities; and hub modules (httptap/models.py, httptap/constants.py, httptap/slo.py) where churn has high blast radius. Medium findings include broad exception handling in httptap/http_client.py, deep nesting (depth 6) in httptap/implementations/dns.py and tls.py, and oversized test files (tests/test_cli.py at 731 lines).

The code health audit flags one high-severity issue in .github/workflows/release.yml: it pushes directly to the default branch instead of opening a pull request, meaning automated commits deploy without prior test verification. The rich dependency is declared as >=14.3.2 but the current major is 15.0.0—one major version behind.

The Bottom Line

httptap is a well-structured, well-tested diagnostic tool with a clear value proposition for anyone debugging HTTP performance. The architecture is sound—the hub modules are stable and the core data flow is straightforward. The main risks are the release workflow pushing directly to main and the duplicated logic scattered across the codebase. Worth using for performance troubleshooting and CI baseline tracking.