reorx/httpstat: curl timing breakdowns for people who do not want to read curl's format string

What reorx/httpstat actually measures

curl already exposes the numbers. The problem is that you have to ask for them with a format string, and the raw output is a list of variables whose names do not map cleanly onto the question you are asking, which is usually "where did the time go". reorx/httpstat wraps curl and prints the same measurements as a labelled breakdown: DNS lookup, TCP connect, TLS handshake, server processing, content transfer, and a total.

The audience is narrow and specific. It is someone at a terminal who has one URL that feels slow and wants to know whether the delay is name resolution, the handshake, the origin server, or the transfer. The README describes the output as a timing breakdown of DNS, TCP, TLS, server processing, and content transfer. That is a single-request instrument. It is not a monitoring agent, and nothing in the repository suggests it schedules repeated requests.

How the wrapper works, and what it does to the request

The project is one Python file, httpstat.py, with no runtime dependencies. It shells out to curl rather than implementing HTTP in Python, which is why the README can say you may pass any curl option after the URL. The exceptions it lists are -w, -D, -o, -s and -S, because httpstat uses those itself to capture the response and the timing variables. Anything else on the command line reaches curl unchanged.

That design has a consequence worth stating plainly: httpstat inherits curl's behaviour, including its TLS stack, its HTTP version negotiation and its proxy handling. If curl on your machine was not built with nghttp2, HTTP/2 will not be available to httpstat either. The README points at issue #12 for that caveat. The HTTPSTAT_CURL_BIN variable exists for exactly this situation, letting you point httpstat at a different curl binary.

By default the response body is written to a temporary file rather than discarded, which HTTPSTAT_SAVE_BODY controls. For a large download that is disk traffic you may not want. The README does not describe a size cap on the saved body, though it does cap the body it will print at 1023 bytes when HTTPSTAT_SHOW_BODY is true.

Installing reorx/httpstat and reading a first run

The README gives three installation routes: downloading the script directly, pip, and Homebrew on macOS. The pip route installs a console entry point, so the command name is httpstat rather than python httpstat.py. For Windows the README does not offer a path of its own; it points at davecheney's Go implementation instead.

pip install httpstat
httpstat httpbin.org/get

The second line performs one request and prints the timing breakdown. You should see the stage names with millisecond values, plus the remote and local IP and port, which are shown by default.

If you would rather not install anything, the README's first option is to fetch the single file and run it with the interpreter:

wget https://raw.githubusercontent.com/reorx/httpstat/master/httpstat.py
python httpstat.py httpbin.org/get

Because it is a curl wrapper, passing curl flags works as you would expect, with the five reserved flags excepted:

httpstat httpbin.org/post -X POST --data-urlencode "a=b" -v

For scripted use, --format json emits a document with a schema_version field set to 1, and --format jsonl emits one compact JSON object per line. The README describes the schema as stable. The timings_ms object carries both derived stages (dns, connect, tls, server, transfer, total) and the underlying curl variables (namelookup, initial_connect, pretransfer, starttransfer), which is useful when you want to check the derived numbers against the raw ones.

SLO thresholds and the exit code 4 contract

The feature that changes httpstat from a viewer into something a script can act on is --slo. You pass comma-separated key=value pairs in milliseconds, and the supported keys are total, connect, ttfb, dns and tls.

httpstat httpbin.org/get --slo total=500,connect=100,ttfb=200

On a violation the process exits with code 4. In pretty mode the offending lines are printed in red at the end. In JSON mode the same information appears in the slo field, with pass set to false and a violations array holding the key, the threshold_ms and the actual_ms. That array is the part to parse; the exit code is the part to branch on.

A single request is a weak basis for a latency budget. The README documents no repetition flag and no percentile output, so an SLO check here tells you about one sample. If you wire it into a pipeline, treat a violation as a signal to look closer rather than as a measurement of the endpoint's typical behaviour.

Environment variables, and the ones that surprise people

Configuration is entirely through environment variables, which the README suggests exporting from .zshrc or .bashrc. HTTPSTAT_SHOW_IP defaults to true, so IP and port addresses appear in output unless you set it to false, which matters if the output is going into a shared log. HTTPSTAT_SHOW_SPEED defaults to false and adds download and upload throughput when enabled. HTTPSTAT_SHOW_BODY defaults to false and truncates at 1023 bytes when enabled.

HTTPSTAT_METRICS_ONLY is the odd one out. Setting it to true makes httpstat emit metrics as JSON only, and the README explicitly marks it as kept for backward compatibility, recommending --format json instead. New work should use the flag. Existing scripts that set the variable will keep working, but it is the kind of duplicate path that eventually diverges.

NO_COLOR is honoured when set to any value, following the no-color.org convention, and HTTPSTAT_DEBUG turns on debug logging. The README does not document a config file, a profile mechanism or per-project settings, so environment variables and flags are the whole surface.

Where reorx/httpstat is the wrong tool

The most important limitation is that httpstat measures one request. There is no concurrency, no request count and no warm-up, so it cannot tell you how an endpoint behaves under load, and it cannot distinguish a cold connection from a reused one across runs. If the question is "how does this service hold up", httpstat answers a different question.

The second limitation is the curl dependency. httpstat does not perform the request itself, so every property of the request comes from whichever curl binary it finds. A curl without HTTP/2 support silently changes what you are measuring, and the README's own workaround is to set HTTPSTAT_CURL_BIN to a specific binary. That is a real operational difference from the Go implementation, which the README describes as written in pure Go and relying on no external programs.

The third is scope. The README documents no redirect chain display, no comparison between two runs and no historical storage. --save writes one JSON file. Anything resembling a trend requires you to build it from the jsonl stream yourself.

Alternatives and the difference in approach

davecheney/httpstat is the closest alternative and the README recommends it for Windows users. The difference is architectural: it is a Go program that makes the request itself, so there is no curl binary in the path and no dependency on how that binary was compiled. The README's own phrasing is that you should choose it if you like solid binary executions. In exchange, you lose the ability to pass arbitrary curl flags through, because there is no curl underneath to receive them.

tcnksm/go-httpstat takes a third position: it is a Go library as well as a CLI, intended for instrumenting HTTP requests inside Go code. That is a different job from diagnosing a URL from a shell, and it only helps if the request you care about is one your Go program makes.

b4b4r07/httpstat is a Bash implementation, and yosuke-furukawa/httpstat is a Node one. The README lists both as related projects. Choosing between them is mostly a question of which runtime you already have and whether you want the Python script's JSON schema and SLO exit code, which the README presents as this project's own additions.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-04-08. The most recent release listed is 1.3.0 from 2020-10-15, with 1.2.1 and 1.2.0 before it in 2016. The gap between the last release and the last push is worth noting: the code has moved since 1.3.0, but there is no tagged release carrying the JSON schema, the SLO flags or the agent skill. If you install from pip you are getting whatever the published package contains, which may not match the repository state the README describes. Installing the script directly from master avoids that mismatch at the cost of tracking an untagged file.

The licence is MIT, declared both in the repository and in pyproject.toml as license = "MIT". MIT is permissive and imposes no copyleft obligation on your own code, but this is a description of the licence text, not legal advice; read LICENSE yourself if the distinction matters to you. The package requires Python 3.9 or later according to pyproject.toml, and the README states compatibility with Python 3.

Upgrade cost is low in the ordinary case, because there are no runtime dependencies to resolve and the tool is one file. The thing to watch is the JSON schema. The README calls the v1 schema stable and the documents carry schema_version: 1, so a consumer that checks that field can detect a future break rather than misparse it.

Editorial conclusion

Adopt it if you debug individual HTTP requests by hand and want the timing split without composing a curl format string, or if you want a JSONL stream and a non-zero exit code for a latency budget check in a script. Do not adopt it as a load generator or an uptime monitor: it makes one request, and the README documents no sampling, concurrency or scheduling. Before relying on the SLO exit code in CI, verify the exit code 4 behaviour on your own curl build, and check which curl binary HTTPSTAT_CURL_BIN resolves to, because the TLS and HTTP/2 numbers depend on how that binary was compiled.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. reorx/httpstat on GitHub