ISP Throttle Detective

Scripts live in scripts/. Log and config default to ~/.isp-throttle-detective/. See references/setup-guide.md for full setup, scheduling, and interpretation guidance.

Workflow

Run a single test and log it

python3 scripts/speedtest.py | python3 scripts/log_result.py

Analyze patterns (needs ≥5 tests across multiple hours/days)

python3 scripts/analyze.py
python3 scripts/analyze.py --days 30 --json   # machine-readable

Generate evidence report

python3 scripts/report.py --days 30 --out ~/report.md

Scripts

Configuration

Copy assets/config.example.json to ~/.isp-throttle-detective/config.json. All scripts auto-detect it. Key fields:

• log_file — where the JSONL log lives
• endpoints — add/remove test targets; set category: "cdn" vs "general" to enable CDN discrimination detection
• peak_hours — list of hours (0–23) considered peak

Pass --config /path/to/config.json to any script to override.

Scheduling

See references/setup-guide.md for launchd (macOS) and cron (Linux) snippets. Recommended: every 30 minutes for meaningful data within a day or two.

Throttling Signals

• Peak-hour drop >20% vs off-peak → time-based throttling
• CDN speed <75% of general internet → destination-based throttling
• Declining trend slope → infrastructure degradation
• Multiple low-speed anomalies at the same hour → systematic, not random

Using the Evidence Report

report.py produces a markdown file with a peak/off-peak comparison table, per-endpoint breakdown, hourly chart, trend analysis, and a plain-English conclusion. Share it directly with ISP support or use it to evaluate whether upgrading your plan would actually help (if CDN throttling is confirmed, a faster plan won't fix it).