Help & Documentation

📡 Overview

ClumsyLinkWatch continuously monitors your internet connection and classifies where a failure happens — your adapter, your router, your ISP's last mile, DNS, or the wider internet. When something breaks, it tells you whose fault it was, and it can export the evidence as an HTML or PDF report.

The app runs quietly in the system tray. You don't need to keep the main window open for monitoring to continue — closing the window minimizes to tray rather than quitting.

⬇ Installation

Download the installer from the Downloads page and run it. No admin rights are required for a per-user install.

▶ First Run

On first launch, ClumsyLinkWatch immediately starts monitoring with sensible defaults:

• Probing every 5 seconds while healthy
• Default DEGRADED thresholds — loss above 1% is flagged, above 3% is treated as a serious problem
• 7 days of history retained (this is the free tier limit — see Settings for details)

You can adjust probe targets, thresholds, and alert channels at any time in Settings.

🪜 The Probe Ladder

Pinging one address and calling a single failed reply an "outage" produces reports that ISPs dismiss — correctly. ClumsyLinkWatch instead checks five rungs, in order, cheapest and closest first, every cycle:

Rung 4 requires a quorum — all anchors down — before declaring an internet outage. One anchor failing on its own is a note, not an event; ISPs and CDNs have their own outages independent of your link.

🏷 Fault Classification

Every detected event carries a class, and the class determines whether it counts against your ISP:

Excluded events aren't hidden — they appear in the timeline and in a report's appendix, so the report can't be accused of cherry-picking data. Hiding them would look worse than showing them.

Why a DEGRADED event fired

"DEGRADED" alone doesn't tell you much — ClumsyLinkWatch records exactly which rung tripped it, whether it was loss or latency, and the measured value against the threshold it crossed. A single cycle can have more than one at once (e.g. DNS loss and ISP-hop latency both over threshold together) — all of them are recorded, not just the first one found. This detail shows up in four places:

• Live, on the status card, for as long as the link stays DEGRADED
• In the event list, as a tooltip on hover
• In generated reports, as a Detail column in the outage table
• On the remote LAN status page

😴 Sleep & Host Gaps

A laptop that sleeps for nine hours must never show up as a nine-hour outage. ClumsyLinkWatch watches Windows power events (suspend, resume, lock) and also detects wall-clock gaps much larger than the sample interval, and marks those spans HOST_SLEEP. They render as hatched gaps in the timeline — never counted as uptime or downtime.

🗂 The Four Screens

The app is split into four screens instead of one long scrolling page, switched with the tabs at the top of the window. The toolbar on the right (Report, Snapshot, Settings, Help, About) stays available on every screen.

📊 Live Dashboard

The Dashboard screen shows current status at a glance: link state, per-rung latency, and the timeline. It's meant to read from across the room — big status, big timeline, everything else secondary. ISP info (public IP, ASN, location) sits below it.

⏱ Reading the Timeline

The timeline strip is proportional to real elapsed time, not to the number of samples — a 2-minute outage and a 2-hour outage look different widths even if each only produced a handful of failed probes.

• Hover any segment for its exact start time, end time, and duration
• Switch between Live / 24h / 7d / 30d zoom levels
• Color-coded by class; sleep gaps are hatched, never solid

📄 Generating Reports

Open Report from the toolbar to generate an HTML or PDF evidence report.

1. Pick a period — 7d / 30d / 90d presets, or a custom range
2. Enter your ISP name, account/circuit number, and location (all optional, but they make the report look like a real document instead of a printout)
3. Optionally enter your monthly bill amount to add a prorated credit estimate (see below)
4. Choose HTML or PDF and generate

The report includes:

• A headline uptime percentage, shown as "nines" too (99.5%, 99.9%) — the language SLAs use
• A plain-English methodology paragraph explaining the probe ladder
• An outage table of ISP-attributable events with evidence summaries
• A full timeline chart and a latency/loss chart with baseline overlay
• An appendix of every excluded event and why, plus raw sample counts
• A speed test summary (average download/upload/latency) and the same recurring-pattern detection from the Speed Test screen, when any tests exist in the period

SLA credit calculation

If you enter a monthly bill amount, the report adds a second headline figure: a prorated credit, computed as a straight line — ISP-attributable downtime as a fraction of the billing period, applied to the bill amount. No multipliers, no penalty math, just "you paid for a month, this much of it didn't work." It's not a legal claim or an ISP-issued credit — it's a defensible starting number for a support call, a billing dispute, or a small-claims filing.

🔔 Alerts & Notifications

ClumsyLinkWatch sends a native desktop notification and flashes the taskbar icon when a real fault starts or ends — DEGRADED and HOST_SLEEP don't trigger the same urgency as a hard outage. You can also configure a Discord- or Slack-compatible webhook URL in Settings to get alerts wherever you already watch for things breaking.

🛰 Hardware Panel

On the Diagnostics screen, the Hardware panel lists your network adapters and, if present, detects a Starlink dish on the LAN. For dual-WAN setups, ClumsyLinkWatch tracks your public IP and records a WAN-state change whenever it changes — a clean failover shows no connectivity gap; a rough one shows exactly how many seconds the failover took.

🚀 Speed Tests & History

The Speed Test screen has a manual "Run Speed Test" button, a day-of-week × hour-of-day pattern heatmap, and a full sortable history — every run, manual or scheduled, is saved.

Scheduling automatic runs

Turn it on in Settings under "Automatic speed tests" — Off, 30 min, 1h, 4h, 12h, or 24h. It's off by default. A real speed test moves real data (roughly 100–300MB per run), so Settings shows a live estimated MB/day next to whichever interval you're considering, and there's a toggle (on by default) to skip a scheduled run while a fault is already active — testing speed during a known outage just times out and adds noise, not evidence.

History and sorting

Click any column header to sort, or use the "Worst download/upload/latency first" buttons to jump straight to your worst readings. Rows note if the link wasn't healthy when a test ran (e.g. "during LAST_MILE_DOWN") — a bad reading during an actual outage isn't your ISP being slow, it's your ISP being down, and the history tells the two apart instead of mixing them together.

Pattern detection

The heatmap buckets every test by day-of-week and hour, and takes the median per cell — deliberately median, not average, so a single freak reading doesn't swing a whole cell. Once enough data exists, a callout appears automatically when a recurring window is meaningfully worse than the rest of your results (e.g. "Tuesdays around 20:00 are consistently 40% below your median download speed") — the kind of pattern that points at peak-hour congestion rather than a one-off. The same detection runs in generated evidence reports.

📶 Remote LAN Status

Turn on Enable Remote LAN Status in Settings to open a small read-only status page on your local network — useful for checking from your phone without remoting into the desktop ClumsyLinkWatch runs on.

• Shows the same big status card as the main app, plus the full probe ladder with live per-rung latency
• Rolling loss percentage and a captive-portal warning banner when one is suspected
• The last 10 events, color-coded by severity
• Auto-refreshes every 5 seconds

Find it at http://<this-computer's-LAN-IP>:<port> from any device on the same network — the port is set in Settings (default 4173); the IP is whatever this computer's own local network address is (check Windows' network settings, or run ipconfig).

⚙ Settings

Key things you can configure:

• ISP name, account/circuit number, and location — pre-fills the report generator
• Webhook URL for Discord/Slack-compatible alerts
• SLA target % and Credit $/day — feeds the live SLA panel's own breach-triggered credit figure
• Enable Remote LAN Status, and its port
• Automatic speed tests — interval (Off/30min/1h/4h/12h/24h) and whether to skip while a fault is active
• DEGRADED thresholds are checked per-rung — a gateway or ISP-hop that's quietly slowed down trips DEGRADED against its own baseline, not just the quorum rung
• History retention (free tier: 7 days)

🛠 Troubleshooting

The app shows "Starting up" and never finishes

This usually means a native module failed to load. Try reinstalling the latest version from the Downloads page; if it persists, send the error banner text to bugs@clumsyslab.tech.

A report shows an outage during a time I know my PC was off or asleep

This should not happen — sleep gaps are excluded by design. If you see it, it's a bug; please report it with the exported report attached.

Updates aren't installing automatically

Open the About screen (ℹ in the toolbar) and click the refresh icon next to the version number to check on demand — it shows "Checking…", then "You're up to date" or "Update vX.X.X available" with a Download button, which becomes Restart Now once downloaded. If nothing shows up after a few seconds, download the latest installer directly from the Downloads page and run it over your existing install.

❓ FAQ

Does this replace my router's built-in monitoring?

No — it complements it. ClumsyLinkWatch is specifically built to produce ISP-facing evidence, not to be a general network management console.

Will this make my connection look worse to my ISP by generating traffic?

No. The scheduler is rate-limited and staggered by design (5s when healthy, 2s during an active event for resolution, backing off to 30s after 10 minutes down) specifically so it never looks like a DoS source.

Is my monitoring data sent anywhere?

No — see the Privacy Policy for details. Everything stays in a local database on your machine.

💬 Support

Email support@clumsyslab.tech for general questions, or bugs@clumsyslab.tech for bug reports. You can also join the Discord.