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>
146 lines
4.2 KiB
Markdown
146 lines
4.2 KiB
Markdown
# latprobe — Website Latency Probe
|
|
|
|
A command-line tool that measures the latency of one or more websites, with a
|
|
**full per-request phase breakdown** — DNS resolution, TCP connect, TLS
|
|
handshake, server processing (time-to-first-byte), and content transfer.
|
|
Not just a ping: `latprobe` shows you _where_ the time goes.
|
|
|
|
## Why
|
|
|
|
A single total request time hides the root cause of slowness. Is it DNS? A slow
|
|
TLS negotiation? A laggy server? `latprobe` breaks the request into its
|
|
constituent phases so the bottleneck is immediately obvious.
|
|
|
|
## Implementations
|
|
|
|
| Language | Status | Location |
|
|
|----------|-----------|------------|
|
|
| Go | In progress | `go/` |
|
|
| Python | Planned | `python/` |
|
|
|
|
Both implementations produce identical CLI behaviour and output formats.
|
|
|
|
---
|
|
|
|
## Usage (Go)
|
|
|
|
```
|
|
latprobe [flags] <url> [url ...]
|
|
|
|
Flags:
|
|
-n, --count int Number of requests per URL (default 1)
|
|
-c, --concurrency int Max URLs probed in parallel, 0 = auto (default min(numURLs,8))
|
|
--timeout duration Request timeout, e.g. 10s, 500ms (default 10s)
|
|
--fail Exit non-zero on HTTP status >= 400 (exit code 6)
|
|
--json Output results as JSON instead of text
|
|
|
|
Examples:
|
|
latprobe https://example.com
|
|
latprobe -n 5 https://example.com https://www.google.com
|
|
latprobe -c 1 -n 10 https://example.com # serial, most accurate
|
|
latprobe --json https://example.com | jq .
|
|
```
|
|
|
|
---
|
|
|
|
## Output
|
|
|
|
### Text (default)
|
|
|
|
```
|
|
https://example.com
|
|
DNS lookup : 12.34 ms
|
|
TCP connect : 8.91 ms
|
|
TLS handshake : 45.20 ms
|
|
Server (TTFB) : 78.56 ms
|
|
Transfer : 2.10 ms
|
|
─────────────────────────
|
|
Total : 147.11 ms
|
|
```
|
|
|
|
With `-n 5` (min / avg / max columns):
|
|
|
|
```
|
|
https://example.com (5 samples)
|
|
min avg max
|
|
DNS lookup : 10.1ms 12.3ms 15.7ms
|
|
TCP connect : 7.8ms 9.0ms 11.2ms
|
|
...
|
|
```
|
|
|
|
### JSON (`--json`)
|
|
|
|
```json
|
|
{
|
|
"url": "https://example.com",
|
|
"samples": 1,
|
|
"phases": {
|
|
"dns": { "ms": 12.34 },
|
|
"connect": { "ms": 8.91 },
|
|
"tls": { "ms": 45.20 },
|
|
"ttfb": { "ms": 78.56 },
|
|
"transfer": { "ms": 2.10 },
|
|
"total": { "ms": 147.11 }
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Roadmap
|
|
|
|
### Go
|
|
|
|
| Step | Feature | Status |
|
|
|------|---------|--------|
|
|
| 0 | Project scaffold — directory structure, `go.mod`, minimal binary | ✅ Done |
|
|
| 1 | Simple total latency — single URL, wall-clock time | ✅ Done |
|
|
| 2 | Per-phase breakdown — DNS, TCP, TLS, TTFB, transfer (`net/http/httptrace`) | ✅ Done |
|
|
| 3 | Multiple URLs + `--count`/`-n` — min/avg/max aggregates | ✅ Done |
|
|
| 4 | `--json` output flag | ✅ Done |
|
|
| 5 | Failure handling — `--timeout`, `--fail`, distinct exit codes, partial timing | ✅ Done |
|
|
| 6 | Integration tests — in-process matrix + subprocess smoke tests | ✅ Done |
|
|
| 7 | Concurrency — `-c` worker pool across URLs; samples stay serial per URL | ✅ Done |
|
|
|
|
### Python
|
|
|
|
Begins after the Go implementation is approved. Will mirror the same CLI and
|
|
output format. Timed using low-level socket hooks (DNS via `socket.getaddrinfo`,
|
|
connection timings via custom socket wrap or `httpx`/`urllib3` hooks).
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
A `Makefile` at the repo root provides all common tasks:
|
|
|
|
```sh
|
|
make # list all targets
|
|
make build # build go/latprobe
|
|
make test # run all tests
|
|
make check # fmt + vet + test (pre-commit gate)
|
|
make go-run ARGS="https://example.com"
|
|
make go-test-verbose
|
|
make go-cover # coverage report → go/coverage.html
|
|
make go-test-race # run tests with race detector
|
|
make go-lint # golangci-lint
|
|
make clean # remove build artifacts
|
|
```
|
|
|
|
See [`docs/usage/makefile.md`](docs/usage/makefile.md) for the full target reference.
|
|
|
|
---
|
|
|
|
## Development Environment
|
|
|
|
- Go 1.26.4 / darwin arm64
|
|
- Python 3.14.6
|
|
- No external dependencies (Go uses stdlib only; Python TBD at port time)
|
|
|
|
## Project Conventions
|
|
|
|
See [CLAUDE.md](CLAUDE.md) for the development conventions followed in this project:
|
|
- Plans saved to `docs/plans/` with timestamped filenames
|
|
- Completed features logged in `CHANGELOG.md` with timestamps
|
|
- Per-feature user docs in `docs/usage/`
|