Jan Novak
6db2abb713
- 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>
334 lines
9.5 KiB
Markdown
334 lines
9.5 KiB
Markdown
# Custom Usage Examples
|
||
|
||
All examples assume the binary has been built first:
|
||
|
||
```sh
|
||
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.**
|
||
|
||
```sh
|
||
./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.**
|
||
|
||
```sh
|
||
./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.**
|
||
|
||
```sh
|
||
./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.**
|
||
|
||
```sh
|
||
./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.**
|
||
|
||
```sh
|
||
./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.**
|
||
|
||
```sh
|
||
./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.**
|
||
|
||
```sh
|
||
./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.**
|
||
|
||
```sh
|
||
./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).**
|
||
|
||
```sh
|
||
./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).**
|
||
|
||
```sh
|
||
./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).
|
||
|
||
```sh
|
||
./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.
|