Promethist Watchdog

Proving the network was the problem

When a kiosk feels slow, the software in front of the customer gets the blame. It is often the network — but nobody was measuring it, and the building’s IT department watches their network, not this machine’s view of it.

So Watchdog measures its own connection on a schedule and keeps the record: one file per day, ten years by default. Months later you can open it in Excel and show that the round trip tripled every weekday at 09:00. It is on by default.

What it measures, and what it costs

Every 5 minutes, a light check: the time to reach three public servers, how many answered, and how long a real web request took to start replying. A few kilobytes. The "how many answered" figure is the one a flaky link fails.

Every hour, a speed test: real download and upload, about 15 MB per test — roughly 360 MB a day. This is the part you may want to turn down. In Settings → Internet connection → Advanced (which shows what your current setting costs per day), set the speed test to never on a metered link, or on a machine whose upload already carries video. The 5-minute check keeps working either way.

Speeds are measured only after the first megabyte has moved, because a connection takes a moment to get up to speed and timing that start would understate every fast link. A transfer too small to measure that way is marked below_warmup rather than passed off as a clean reading.

The files

<log_root>\network\2026-08-04.csv

wdog network --path prints today’s. They are deliberately not in the per-day log folders (Logs), which are deleted after 30 days. One file per day so a corrupted write — a power cut mid-append — costs one day, not the whole history.

Open one in Excel; it has a header row.

Column What it means

ts_utc, ts_local

The same moment twice. Sort by UTC (it survives daylight saving); quote local to the customer.

sample

light, or full when the speed test also ran.

online

1 if any server answered, 0 if none did.

ping_ms

Fastest round trip of the servers that answered.

ping_hosts_ok / _total

How many answered, out of how many were tried.

ttfb_ms

How long a real web request took to start replying.

down_mbps, up_mbps

Speed, on full rows only. Blank means not measured, never zero.

down_bytes, up_bytes

How much actually moved, so a short or timed-out transfer is visible.

note

Why a reading is missing or qualified: the error, below_warmup, timed_out.

To hand a month to a customer’s IT department, zip that folder.

From the command line

wdog network                     today, summarised
wdog network --day 2026-08-04    an earlier day
wdog network --test              measure right now and print it
wdog network --path              the path of today's file

Run --test once when commissioning a machine. It is the only check that proves the measurement works there — otherwise a PC that cannot reach the test servers would quietly record outages that never happened.

In the window, the machine strip gains a NET reading: last round trip and last measured speed, amber past 100 ms, red past 300 ms, offline when nothing answered.

Emails and retention

Two events, both on by default (Email alerts): network_down after several failed checks in a row (three by default, ~15 minutes), and network_restored when it comes back, with how long it was gone.

The network_down alert has to travel over the connection that just failed, so in a real outage it usually does not arrive — and a two-day-old "the internet is down" email would be worse than none. network_restored is the one that reaches you, and it carries the outage’s length. Every check is written to the file regardless.

Two limits, whichever is reached first, always deleting the oldest days and never today’s: retention_days (3650, or 0 to keep everything) and max_total_mb (512 — a safety net, since ten years of these files is under 100 MB). The nightly sweep only touches files named YYYY-MM-DD.csv.

Pointing it somewhere else

The speed test uses Cloudflare’s public endpoints and the round trip goes to public DNS servers. Some sites will not want either:

wdog config set network_test.ping_hosts -- 10.1.2.1:53 10.1.2.2:53
wdog config set network_test.download_url https://files.internal/10mb.bin
wdog config set network_test.upload_url https://files.internal/upload

Measuring against a server inside the building answers a different question — the local network rather than the internet — which is sometimes the one worth asking. Whichever you pick, keep it the same, or a year of readings will not compare.