Jan Novak
45583ac2be
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>
296 lines
7.6 KiB
Markdown
296 lines
7.6 KiB
Markdown
# Custom Usage Examples
|
||
|
||
All examples assume the binary has been built first:
|
||
|
||
```sh
|
||
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.**
|
||
|
||
```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: ~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.**
|
||
|
||
```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: ~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.**
|
||
|
||
```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: ~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.**
|
||
|
||
```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: ~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.**
|
||
|
||
```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: ~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.**
|
||
|
||
```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: ~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.**
|
||
|
||
```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: ~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.**
|
||
|
||
```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: ~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).**
|
||
|
||
```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: ~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).**
|
||
|
||
```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: ~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.
|