yslow 0.3.1

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.

╻ ╻┏━┓╻  ┏━┓╻ ╻┏━┓
┗┳┛┗━┓┃  ┃ ┃┃╻┃ ╺┛
 ╹ ┗━┛┗━╸┗━┛┗┻┛ ╹

Is it slow?
● YES!

Why?
  ⚠ network no targets reachable (internet may be down) (1x, ongoing)
  ⚠ LAN     gateway unreachable (unusual routing setup) (1x, ongoing)

Details
  LAN:          gateway 192.168.1.1 unreachable
  ISP/internet: all targets unreachable
  10.0.0.1:       3.0 ms cached,  45.0 ms uncached ✱
  Google DNS:    25.0 ms cached,  60.0 ms uncached
  OpenDNS:       35.0 ms cached,  42.0 ms uncached
  Cloudflare DNS:  9.0 ms cached,  40.0 ms uncached

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).
• DNS resolution — cached and uncached lookup times for your configured resolver and public resolvers (Google, Cloudflare, OpenDNS). Flags slow resolvers and compares your configured resolver against public alternatives.
• Packet loss — at both the local and internet level.
• Jitter — variance in latency, which causes buffering, choppy calls, and inconsistent page loads.

Usage

uvx yslow              # one-shot check
uvx yslow -w           # continuous monitoring (every 30s)

Requires Python 3.10+. Works on Linux and macOS.

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, 22) and falls back to ICMP ping if needed.

Development

uv sync                  # install deps
./check.sh               # run all checks (format, lint, typecheck, tests)
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, DNS), how each metric is calculated, and the thresholds used for diagnosis.

Planned

• Bufferbloat detection (latency under load)
• Bandwidth / throughput estimation
• IPv6 health check
• Route analysis (where along the path is the bottleneck)

See TODO.md for more