netpath

Network path diagnostics for AS paths, exact service endpoints, and regional probe coverage. netpath combines traceroute/MTR, optional iperf3 throughput, latency/loss/jitter checks, DNS and HTTPS edge timing, PMTU/geo sanity checks, Globalping remote probes, and Cloudflare Radar RUM overlays.

Install

pip install netpath
# or
uvx netpath
# or
uv tool install netpath

System tools:

# macOS
brew install mtr iperf3

# Debian / Ubuntu
sudo apt install mtr-tiny iperf3

# Fedora / RHEL
sudo dnf install mtr iperf3

mtr is the preferred path prober; traceroute is used as a fallback when available. iperf3 enables cross-ASN throughput tests; without it, netpath falls back to a Cloudflare HTTP speedtest baseline where relevant.

Quickstart

# Diagnose a specific service endpoint
netpath host zoom.us

# Generate an escalation-ready root-cause report
netpath explain zoom.us --baseline ~/.netpath/monitor/AS15169.jsonl

# Probe one ASN
netpath asn AS15169

# Sweep top ASNs in a country
netpath country US --top 5

# Monitor path regressions over time
netpath monitor AS15169 --target zoom.us --every 10m

# Compare measured paths between ASNs or cities
netpath aspath AS7922 AS7018
netpath citypath "Los Angeles" "Tokyo"

# Check global DNS propagation in an interactive TUI
netpath dns example.com A

Use --json on commands that support scripting output. For DNS, use --once for the non-interactive terminal snapshot.

Command guide

Common options

Run netpath <command> --help for the full option list.

Endpoint vs ASN mode

Use host when troubleshooting an application path. It bypasses representative ASN/city target selection and traces the resolved endpoint directly, which matters for DNS steering, CDNs, Anycast, and SaaS edges.

Use asn, country, aspath, and citypath when characterizing networks or comparing providers. Those modes intentionally select usable targets or remote probes to answer broader path questions.

Interactive TUI

Launch the full-screen network analyzer:

netpath

You can optionally start with a path prefilled:

netpath tui "Denver" "Tel Aviv"
netpath tui AS14593 AS12400 --asn

The TUI is the default interface and includes city and ASN path ranking, endpoint traces, ASN and country tests, DNS propagation, incident explanations, reusable baselines, target discovery, and Globalping coverage. Use Create baseline to save a measurement; Explain incident automatically lists the available JSON/JSONL baselines in a dropdown. Existing subcommands remain available for scripts and automation. Path views show each geolocated hop with RTT and network ownership, plot an approximate terminal route, and can open the result on the browser globe. Press Ctrl+R to run, m to cycle modes, g for the globe, and q to quit.

Check the installed version with netpath --version or netpath -V.

Monitoring

monitor stores JSONL history under ~/.netpath/monitor by default:

netpath monitor AS15169
netpath monitor AS15169 --every 10m --runs 6
netpath monitor AS15169 --target zoom.us --every 10m
netpath monitor AS15169 --forever --every 5m --webhook https://example.com/netpath-alert

Standard mode keeps one history file per ASN. --target mode keys history by ASN plus resolved endpoint, so application-specific baselines do not mix with representative ASN baselines. Add --fail-on-regression for cron or CI jobs.

Monitor snapshots include recent route-stability summaries: AS-path churn rate, median/p95 RTT baseline, and severity frequency.

Globalping and RUM

Globalping is used for remote, inside-out measurements without requiring an account. A token is optional and only raises rate limits:

export NETPATH_GLOBALPING_TOKEN=your_token_here
netpath country ZA --top 10

Cloudflare Radar RUM overlays need a free token with radar:read permission:

export NETPATH_CF_TOKEN=your_token_here
netpath asn AS15169

Target discovery

When netpath needs a target inside an ASN, it tries self-hosted/registered iperf3 servers (local registry and NETPATH_SERVERS_URL lists), public iperf3 servers, connected RIPE Atlas probe addresses, PeeringDB IXP interface addresses, then a small verified sample from RIPEstat announced prefixes. User-provided targets are preserved and annotated with Cymru ASN/prefix attribution.

Host an iperf3 server in your ASN

Real cross-ASN throughput numbers require an iperf3 server inside the target network, and public coverage is sparse. If you operate a network, one command fills the gap:

netpath serve

That runs iperf3 -s, detects your public IP and ASN via Cymru, registers the server in ~/.netpath/servers.json, and prints everything needed to make it discoverable to others. Open TCP+UDP 5201.

Prefer containers, systemd, or cloud-init? Deployment assets ship with the package:

netpath serve --emit install | sudo sh    # iperf3 + hardened systemd unit
netpath serve --emit compose              # docker-compose.yml (with --emit docker for the Dockerfile)
netpath serve --emit cloud-init           # user-data for a fresh VM

Discovery works at whatever radius you want:

• Just you — the local registry written by netpath serve is merged ahead of the public list.
• Your org or community — host the printed JSON entry anywhere and point users at it with NETPATH_SERVERS_URL=https://… (comma-separated URLs allowed), or run the reference community registry (netpath serve --emit registry) and announce servers to it with netpath serve --announce https://registry…/register.
• Anyone probing your domain — publish the printed DNS SRV record (_netpath-iperf3._tcp.example.com); netpath host example.com --throughput finds and uses the record owned by that exact domain.
• Everyone — submit the entry to the public iperf3 server list, which every netpath install checks.

See src/netpath/deploy/README.md for the full operator guide.

Development

make validate  # syncs dev extras, then runs tests and lint
make test      # uv run python -m pytest -q
make lint      # uv run python -m ruff check .

Maintainer release flow

Releases are tag-driven. Cut them from main with the local helper:

release-tag v0.27.0 "Describe the change"

The helper verifies main, runs tests, pushes the commit/tag, and the v*.*.* tag triggers PyPI publishing plus GitHub Release creation via GitHub Actions.

License

MIT