How to capture response metrics with cURL write-out

Capturing response metrics with curl using write-out exposes HTTP status codes, timing breakdowns, and transfer sizes for each HTTP request, which simplifies analysis of slow endpoints and validation of API behavior under different conditions. Compact metric summaries make it easier to compare responses over time or across environments without storing full response bodies.

The curl –write-out option expands placeholders such as {http_code}, {time_total}, and {size_download} after the transfer completes, printing a formatted summary to standard output. Combining –write-out with –output for the response body and –silent for progress suppression keeps metrics separate from content while still surfacing errors with –show-error.

On Ubuntu and other Linux distributions, write-out variables behave consistently across HTTP and HTTPS, but certain placeholders remain empty for protocols that do not expose specific timing or size values. Logging formats must account for shell quoting, avoid including sensitive data such as tokens in URLs or headers, and rotate metric logs so repeated requests do not exhaust disk space.

1. Define a write-out format file that records key response metrics in a stable, parseable layout.

   $ cat > curl-format.txt <<'EOF'
   http_code=%{http_code}\n
   remote_ip=%{remote_ip}\n
   remote_port=%{remote_port}\n
   scheme=%{scheme}\n
   time_namelookup=%{time_namelookup}\n
   time_connect=%{time_connect}\n
   time_appconnect=%{time_appconnect}\n
   time_pretransfer=%{time_pretransfer}\n
   time_starttransfer=%{time_starttransfer}\n
   time_total=%{time_total}\n
   size_download=%{size_download}\n
   speed_download=%{speed_download}\n
   EOF

   Grouping write-out variables in a dedicated file keeps metrics consistent across commands and avoids complex shell escaping of {variable} placeholders.

2. Send an HTTPS request using curl with the write-out format file and capture the response body separately.

   $ curl --silent --show-error --output response.json --write-out @curl-format.txt --cacert /work/docker/certs/ca.crt https://api.example.net/headers
   http_code=200
   remote_ip=127.0.0.1
   remote_port=443
   scheme=HTTPS
   time_namelookup=0.000542
   time_connect=0.000607
   time_appconnect=0.003346
   time_pretransfer=0.003386
   time_starttransfer=0.044832
   time_total=0.044918
   size_download=105
   speed_download=2337

   The –silent option suppresses the progress bar, –show-error keeps error messages visible, and –output response.json stores the body separately from the metrics.

3. Append write-out metrics to a log file so every request adds a new set of timing and size values.

   $ curl --silent --show-error --output /dev/null --write-out @curl-format.txt --cacert /work/docker/certs/ca.crt https://api.example.net/headers >> curl-metrics.log

   Metric logs recorded during frequent or automated requests can grow rapidly and may reveal sensitive paths or query strings, so unbounded logging on shared systems risks information leakage and disk exhaustion.

4. Capture metrics for multiple requests in a single run using a simple loop that repeats the curl call.

   $ for i in $(seq 1 3); do curl --silent --show-error --output /dev/null --write-out @curl-format.txt --cacert /work/docker/certs/ca.crt https://api.example.net/headers >> curl-metrics.log; echo >> curl-metrics.log; done

   Appending an empty line after each run separates metric blocks, which simplifies parsing and visual inspection in tools such as awk or grep.

5. Inspect the metrics log and confirm that each request adds a new block of values with the expected status codes and timings.

   $ cat curl-metrics.log
   http_code=200
   remote_ip=127.0.0.1
   remote_port=443
   scheme=HTTPS
   time_namelookup=0.000284
   time_connect=0.000340
   time_appconnect=0.003172
   time_pretransfer=0.003208
   time_starttransfer=0.047803
   time_total=0.047841
   size_download=105
   speed_download=2194
   
   http_code=200
   remote_ip=127.0.0.1
   remote_port=443
   scheme=HTTPS
   time_namelookup=0.000199
   time_connect=0.000248
   time_appconnect=0.002561
   time_pretransfer=0.002584
   time_starttransfer=0.046792
   time_total=0.046842
   size_download=105
   speed_download=2241

   Stable values for http_code and reasonable ranges for time_total and speed_download indicate successful requests and usable timing data for trend analysis.