Capture a curl trace

Verbose mode shows headers and events. Sometimes that’s not enough. A transfer dies halfway through the body. A server misbehaves on specific bytes. Or you need to hand a complete record to someone else.

A trace goes deeper than verbose mode. It records every byte sent and received, with timestamps. It’s the tool for a small, controlled reproduction of a problem.

Record a trace

Capture a readable trace with timestamps:

curl --trace-ascii trace.txt --trace-time https://example.org/ -o /dev/null

Nothing extra appears on screen. The record lands in trace.txt:

17:20:31.234567 == Info: Connected to example.org (104.20.26.136) port 443
17:20:31.301234 => Send header, 76 bytes (0x4c)
0000: GET / HTTP/2
000e: Host: example.org
...
17:20:31.398765 <= Recv header, 13 bytes (0xd)
0000: HTTP/2 200
17:20:31.401122 <= Recv data, 1256 bytes (0x4e8)

The direction markers guide you. => is data curl sent. <= is data curl received. == Info lines are curl’s own commentary. Every block shows its byte count, and --trace-time stamps each line, so you can see exactly where the time went.

That combination answers questions verbose mode can’t. A transfer that hangs shows a timestamp gap at the exact byte where it stalled. A response cut short shows fewer received bytes than the headers promised.

--trace-ascii keeps the output readable by replacing non-printable bytes with dots. When the exact byte values matter, like debugging a compressed or binary response, use --trace trace.bin instead. You get a full hex dump.

Make the trace worth keeping

A trace is a reproduction artifact. Keep its context with it: the exact command and the curl version.

curl --version > repro-notes.txt
echo 'curl --trace-ascii trace.txt --trace-time https://example.org/ -o /dev/null' >> repro-notes.txt

Whoever picks this up later, including you in six months, can rerun the same transfer and compare the traces line by line. A trace without the command that produced it is half the evidence.

A trace records everything

That’s the design, and it’s also the risk. Trace files contain credentials, cookies, URLs, and full request and response bodies.

Use disposable data when you can. Sanitize before you share. A trace made with a real session cookie is a working credential sitting in a text file. I treat trace files like I treat cookie jars: they don’t leave my machine until I’ve read every line.

Try it: trace a request to an endpoint that returns JSON, like https://httpbin.org/get. Find the <= Recv data block and check that its byte count matches the content-length header a few lines above it.