Files

Jan Novak 45583ac2be docs: add 10 custom usage examples covering all failure modes

Examples 1-3: clean global sweep (single, 10 samples, JSON).
Examples 4-8: one failure type each (DNS, refused, timeout, HTTP, TLS).
Example 9: full matrix, all 5 failure types in one run.
Example 10: quick smoke test (-n 1, JSON, --timeout 2s, all types).
Includes runtime estimates and jq filter snippets.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-07-01 01:16:39 +02:00

7.6 KiB

Raw Blame History

Custom Usage Examples

All examples assume the binary has been built first:

make build
# binary is now at go/latprobe

Estimated runtimes assume a typical home broadband connection. 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: ~30 s — 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: ~3–5 min — best for spotting jitter and TTFB variance.

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: ~3–5 min.

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: ~2–3 min — DNS failures resolve near-instantly.

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: ~2–3 min — refused connections fail immediately.

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: ~3–4 min — timeout IPs add 3 s × 10 samples = 30 s each.

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: ~2–3 min — full timing captured even for error responses.

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: ~2–3 min — TLS failures surface DNS + connect timing.

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: ~5–7 min — the comprehensive stress test.

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: ~30–60 s — fastest end-to-end check of all error paths.

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.

7.6 KiB Raw Blame History Unescape Escape