Jan Novak
9a69ba946f
Probe multiple URLs in parallel with a bounded worker pool; the N samples of each URL remain sequential to preserve accurate min/avg/max statistics. Default auto-concurrency is min(numURLs, 8); -c 1 restores serial mode. Output is always buffered and printed in original input order. Verified clean with go test -race. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
8.2 KiB
Custom Usage Examples
All examples assume the binary has been built first:
make build
# binary is now at go/latprobe
Concurrency note: Since Step 7, latprobe probes URLs in parallel by default
(min(numURLs, 8) workers). Estimated runtimes below reflect this — they are
roughly slowest-single-URL × samples rather than the sum across all URLs.
Use -c 1 to restore serial execution for the most accurate per-phase numbers.
The timeout flag is shortened to --timeout 3s wherever non-routable IPs are
used, so each timed-out sample fails in 3 s instead of the default 10 s.
Example 1 — Clean global sweep, text output (single sample)
10 sites distributed across continents, one request each. All sites accessible. Exit code: 0.
./go/latprobe \
https://www.google.com \
https://www.bbc.co.uk \
https://www.lemonde.fr \
https://www.spiegel.de \
https://www.yahoo.co.jp \
https://www.alibaba.com \
https://www.globo.com \
https://www.abc.net.au \
https://www.thehindu.com \
https://www.timeslive.co.za
Estimated runtime: ~5–8 s — all 10 sites measured in parallel; shows per-phase breakdown once per site.
Example 2 — Clean global sweep, 10 samples, text output
Same 10 sites, 10 requests each — reveals real latency distribution (min/avg/max). All sites accessible. Exit code: 0.
./go/latprobe -n 10 \
https://www.google.com \
https://www.bbc.co.uk \
https://www.lemonde.fr \
https://www.spiegel.de \
https://www.yahoo.co.jp \
https://www.alibaba.com \
https://www.globo.com \
https://www.abc.net.au \
https://www.thehindu.com \
https://www.timeslive.co.za
Estimated runtime: ~20–30 s — 8 workers run in parallel; wall time ≈ slowest single URL × 10 samples.
Example 3 — Clean global sweep, 10 samples, JSON output
Same as Example 2, machine-readable. Pipe into jq to extract specific phases.
All sites accessible. Exit code: 0.
./go/latprobe -n 10 --json \
https://www.google.com \
https://www.bbc.co.uk \
https://www.lemonde.fr \
https://www.spiegel.de \
https://www.yahoo.co.jp \
https://www.alibaba.com \
https://www.globo.com \
https://www.abc.net.au \
https://www.thehindu.com \
https://www.timeslive.co.za
# Extract average total latency per site:
./go/latprobe -n 10 --json \
https://www.google.com https://www.bbc.co.uk https://www.lemonde.fr \
https://www.spiegel.de https://www.yahoo.co.jp https://www.alibaba.com \
https://www.globo.com https://www.abc.net.au https://www.thehindu.com \
https://www.timeslive.co.za \
| jq '.[] | {url, avg_total_ms: .phases.total.avg_ms}'
Estimated runtime: ~20–30 s.
Example 4 — DNS failures mixed in (exit code 2)
8 accessible sites + 2 non-existent domains.
The .invalid TLD is guaranteed NXDOMAIN by RFC 6761.
Expected exit code: 2.
./go/latprobe -n 10 \
https://www.google.com \
https://www.bbc.co.uk \
https://www.lemonde.fr \
https://www.spiegel.de \
https://www.yahoo.co.jp \
https://www.alibaba.com \
https://www.globo.com \
https://www.abc.net.au \
https://nonexistent-host-one.invalid \
https://nonexistent-host-two.invalid
Estimated runtime: ~20–30 s — DNS failures resolve near-instantly; 8 workers run in parallel.
Example 5 — Connection refused mixed in (exit code 3)
8 accessible sites + 2 localhost ports with nothing listening. Expected exit code: 3.
./go/latprobe -n 10 \
https://www.google.com \
https://www.bbc.co.uk \
https://www.lemonde.fr \
https://www.spiegel.de \
https://www.yahoo.co.jp \
https://www.alibaba.com \
https://www.globo.com \
https://www.abc.net.au \
http://127.0.0.1:1 \
http://127.0.0.1:19999
Estimated runtime: ~20–30 s — refused connections fail immediately; 8 workers run in parallel.
Example 6 — Timeout failures mixed in (exit code 4)
8 accessible sites + 2 non-routable IPs (RFC 5737 documentation range,
packets are dropped by the network). --timeout 3s keeps each failed
sample to 3 s instead of the default 10 s.
Expected exit code: 4.
./go/latprobe -n 10 --timeout 3s \
https://www.google.com \
https://www.bbc.co.uk \
https://www.lemonde.fr \
https://www.spiegel.de \
https://www.yahoo.co.jp \
https://www.alibaba.com \
https://www.globo.com \
https://www.abc.net.au \
https://192.0.2.1 \
https://203.0.113.1
Estimated runtime: ~35–40 s — all 10 URLs measured in parallel; the 2 timeout IPs each add 3 s × 10 samples = 30 s and are the bottleneck.
Example 7 — HTTP error status with --fail (exit code 6)
8 accessible sites + 2 URLs that return 4xx/5xx. Without --fail these
would exit 0; with it, exit code becomes 6.
Expected exit code: 6.
./go/latprobe -n 10 --fail \
https://www.google.com \
https://www.bbc.co.uk \
https://www.lemonde.fr \
https://www.spiegel.de \
https://www.yahoo.co.jp \
https://www.alibaba.com \
https://www.globo.com \
https://www.abc.net.au \
https://httpbin.org/status/404 \
https://httpbin.org/status/503
Estimated runtime: ~20–30 s — full timing captured even for error responses; all 10 URLs measured in parallel.
Example 8 — TLS failures mixed in (exit code 5)
8 accessible sites + 2 HTTPS servers with bad certificates.
badssl.com is a purpose-built TLS testing service.
Expected exit code: 5.
./go/latprobe -n 10 \
https://www.google.com \
https://www.bbc.co.uk \
https://www.lemonde.fr \
https://www.spiegel.de \
https://www.yahoo.co.jp \
https://www.alibaba.com \
https://www.globo.com \
https://www.abc.net.au \
https://self-signed.badssl.com \
https://expired.badssl.com
Estimated runtime: ~20–30 s — TLS failures surface DNS + connect timing; all 10 URLs measured in parallel.
Example 9 — All failure types, full matrix (exit code 5)
10 accessible sites + one of each failure class. Exercises every code path:
DNS (exit 2), connect (exit 3), timeout (exit 4), TLS (exit 5),
HTTP error with --fail (exit 6). Highest code wins → exit 5 (TLS is
5, HTTP error is 6 — but exit 6 if httpbin is reachable).
Expected exit code: 6 (with --fail).
./go/latprobe -n 10 --fail --timeout 3s \
https://www.google.com \
https://www.bbc.co.uk \
https://www.lemonde.fr \
https://www.spiegel.de \
https://www.yahoo.co.jp \
https://www.alibaba.com \
https://www.globo.com \
https://www.abc.net.au \
https://www.thehindu.com \
https://www.timeslive.co.za \
https://nonexistent-host.invalid \
http://127.0.0.1:1 \
https://192.0.2.1 \
https://httpbin.org/status/500 \
https://self-signed.badssl.com
Estimated runtime: ~35–45 s — 15 URLs measured with 8 workers; the 2 timeout IPs (30 s × each) are the bottleneck.
Example 10 — Quick smoke test, single sample, JSON, all failure types
Same 15 targets as Example 9 but -n 1 for a fast sanity check.
JSON output lets you pipe results to jq for filtering.
Expected exit code: 6 (with --fail).
./go/latprobe -n 1 --fail --timeout 2s --json \
https://www.google.com \
https://www.bbc.co.uk \
https://www.lemonde.fr \
https://www.spiegel.de \
https://www.yahoo.co.jp \
https://www.alibaba.com \
https://www.globo.com \
https://www.abc.net.au \
https://www.thehindu.com \
https://www.timeslive.co.za \
https://nonexistent-host.invalid \
http://127.0.0.1:1 \
https://192.0.2.1 \
https://httpbin.org/status/500 \
https://self-signed.badssl.com
# Show only failed entries:
./go/latprobe -n 1 --fail --timeout 2s --json \
https://www.google.com \
https://nonexistent-host.invalid \
http://127.0.0.1:1 \
https://192.0.2.1 \
https://httpbin.org/status/500 \
https://self-signed.badssl.com \
| jq '.[] | select(.failed > 0 or .status >= 400)'
Estimated runtime: ~4–6 s — 15 URLs probed in parallel with -n 1; only the 2 s timeout IPs add meaningful delay.
Exit code reference
| Code | Meaning |
|---|---|
| 0 | All probes succeeded |
| 1 | Usage error |
| 2 | DNS resolution failure |
| 3 | Connection failure |
| 4 | Timeout |
| 5 | TLS handshake failure |
| 6 | HTTP status ≥ 400 (only with --fail) |
When multiple failure types occur, the process exits with the highest code.