yslow 0.3.0

Diagnose why your network connection is slow

yslow

A command-line tool that diagnoses why your network connection is slow (or feels slow).

Instead of just reporting numbers, yslow isolates where the problem is — your local network (wifi/router), your ISP, or the broader internet — and tells you in plain language.

What it checks

• Gateway latency — how fast your machine can talk to your router. High latency or jitter here points to wifi congestion, a bad cable, or an overloaded router.
• Internet latency — TCP handshake time to multiple well-known servers (Cloudflare, Google, OpenDNS).
• Packet loss — at both the local and internet level.
• Jitter — variance in latency, which causes buffering, choppy calls, and inconsistent page loads.

By comparing gateway vs internet results, yslow isolates the problem:

Gateway	Internet	Diagnosis
Fast	Fast	Connection is healthy
Slow	Slow	Local network is the bottleneck (router/wifi)
Fast	Slow	ISP or internet routing issue
Unreachable	Slow	Unusual setup, but internet works

Usage

uv run yslow

Requires Python 3.10+ and Linux. No dependencies beyond the standard library.

How it works

yslow uses TCP handshake timing rather than ICMP ping. A TCP connect to port 443 measures the same network round-trip as ping, but works without root privileges and inside containers where ICMP is often blocked.

For the gateway, it tries common TCP ports (80, 443, 53) and falls back to ICMP ping if needed.

Development

uv sync                  # install deps
./check.sh               # run all checks (format, lint, typecheck, tests)
uv run pytest            # run tests only
uv run ty check          # type check only
uv run ruff check --fix  # lint
uv run ruff format       # format

Documentation

See docs/metrics.md for details on what yslow measures (RTT, packet loss, jitter), how each metric is calculated, and the thresholds used for diagnosis.

Planned

• DNS resolution timing
• Bandwidth / throughput estimation
• Bufferbloat detection (latency under load)
• Route analysis (where along the path is the bottleneck)