Files

Jan Novak 6db2abb713 feat(py): step 1 refinement — error-path example configs for simple.py

- python/configs/: 7 purpose-built config files, one per error class:
  all-ok.txt, dns-failure.txt, connection-refused.txt, timeout.txt,
  tls-errors.txt (badssl.com), http-errors.txt (real 404 paths on stable
  hosts), mixed.txt (one of each, no timeout)
- python/configs/usage.md: runnable sh commands + expected output per config,
  plus quick-sweep and full-sweep loops; commands written for running from
  the python/ directory
- docs/custom-usage-examples.md: example 11 added (all failure classes at once)
- docs/usage/py-simple.md: added pointer to python/configs/ and corrected
  limitation note (4xx/5xx are FAIL, not OK)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-01 11:58:20 +02:00

9.5 KiB

Raw Blame History

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.

Example 11 — 3 working sites, one of each error kind (exit code 6)

Minimal URL set that exercises every failure class simultaneously. Three real sites succeed; five targets each trigger a distinct error. --fail is required to surface the HTTP 4xx as an exit code. Expected exit code: 6 (highest code wins; HTTP error = 6 > TLS = 5 > timeout = 4 > refused = 3 > DNS = 2).

./go/latprobe -n 5 --fail --timeout 3s \
  https://www.cloudflare.com \
  https://www.github.com \
  https://www.wikipedia.org \
  https://nonexistent-host.invalid \
  http://127.0.0.1:1 \
  https://192.0.2.1 \
  https://self-signed.badssl.com \
  https://httpbin.org/status/404

URL	Expected outcome	Exit-code contribution
cloudflare.com	success	—
github.com	success	—
wikipedia.org	success	—
nonexistent-host.invalid	DNS failure	2
127.0.0.1:1	connection refused	3
192.0.2.1	timeout (3 s × 5 samples)	4
self-signed.badssl.com	TLS handshake failure	5
httpbin.org/status/404	HTTP 404 (with --fail)	6

Estimated runtime: ~18–22 s — 8 workers cover all URLs in parallel; the non-routable IP (192.0.2.1) drives the wall time at 3 s × 5 samples = 15 s.

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.

9.5 KiB Raw Blame History Unescape Escape