Log Internet Outages From a Raspberry Pi or NAS

By Paul Snyman · Published · 8 min read

An outage you only noticed is an anecdote. An outage with a start time, an end time and a note that your router kept answering the whole way through is evidence. The difficulty is that drops happen at 3 a.m. and on weekday afternoons, when nobody is watching, and the device you would watch from, a phone or a laptop, is asleep or in a pocket. A Raspberry Pi or a NAS is neither. It stays on, it sits on your network beside the router, and it can check the line every minute for months.

This guide covers what a useful outage log records, a do-it-yourself version with a shell loop, and how PingKit Agent for Docker and Raspberry Pi keeps that log for you and turns it into a report for your provider.

Why a device that stays on

A phone app can only check while it is open on screen, and a laptop stops checking when it sleeps. Every gap in the record is a stretch your provider can say nothing happened in. A small computer that stays on closes those gaps:

It watches while it stays on. If the Pi itself loses power, that time is recorded as unmonitored rather than as an outage, so give the monitor a power supply you trust.

What a log your provider will take seriously records

The do-it-yourself version: a ping loop

If you only want a rough timeline, a few lines of shell on the Pi will do. This logs one line a minute, with the time and whether a public address answered:

while true; do
  if ping -c 1 -W 2 1.1.1.1 > /dev/null 2>&1; then s=up; else s=down; fi
  echo "$(date -Iseconds) $s" >> ~/internet.log
  sleep 60
done

It works, and plenty of people have won an argument with less. Its limits are the reasons the rest of this guide exists: one failed ping is not an outage, it cannot tell your router from your line or DNS from both, it does not know when it was itself stopped, and the result is a text file you still have to summarise for someone else.

Log outages with PingKit Agent

PingKit Agent runs on the Pi, the NAS or the Docker host and watches your own network. Install it from the Raspberry Pi guide or the Docker and NAS page. For outages it does this:

Verdicts say "looks like". The agent infers where a fault is from which checks answered. "Looks like your router or Wi-Fi did not answer", "Looks like your ISP's line is down", "Looks like DNS only" and "Looks like this monitor lost its own connection" are what it saw from your network, not a finding about your provider's equipment.

Honest times, and the gaps

The agent stores every outage as two windows. It began after the last good check and by the first failed one, and ended after the last failed check and by the first good one, so the record reads "Began between 14:02 and 14:03" rather than pretending to a precision it does not have. Lengths come from the monitor's own steady clock, and the report says when the device's clock may have been wrong, which matters on a Raspberry Pi without a real-time clock.

Time the agent was not running, because the Pi was unplugged, the container stopped or the clock jumped, is counted as unmonitored, never as connected, and is left out of the monitored share. A log that quietly fills its own gaps with "up" is the first thing a provider will pick apart.

Who hears about it, and when

When the whole line is down, the agent cannot send anything out. What it can reach depends on where the listener is:

If it was the monitor's own connection that dropped, its cable, its Wi-Fi or a router it is cabled into losing power, the agent says so: "This monitor lost its own connection from 14:02 to 14:19 (17 min)."

Turn the log into an Internet Outage Report

With PingKit Guardian, PingKit on your iPhone builds an Internet Outage Report from the agent's records: a PDF, with the data file it was made from exported beside it. It carries:

The report is produced in all 27 languages of the app, and includes a short guide to reading it, so the person on the other end of your complaint can follow it without PingKit.

Notes for your country

The report adds a note for the United Kingdom, Germany and the United States, saying what a complaint there rests on. None of them promises an outcome; the report is evidence, and the rules are the regulator's.

What is free, and what Guardian adds

Running the agent is free. So are its own pages in your browser, which show 30 days of outages on a chart, and its alerts to your own services: ntfy, Telegram, Discord, Pushover, a webhook or apprise-api. The outage log on your iPhone, the push when the line drops and the Internet Outage Report need PingKit Guardian: $2.99 a month or $24.99 a year on iPhone, with a 1-week free trial. The agent keeps a year of outages on disk either way.

Frequently Asked Questions

Why log outages from a Raspberry Pi or NAS instead of my phone?

An iPhone app can only check the line while it is open on screen, and a laptop stops checking when it sleeps. A Raspberry Pi or NAS stays on, so it can check once a minute through the night and keep the record whether or not you are looking.

How short an outage does PingKit Agent record?

It checks once a minute and records Internet Down after three checks in a row fail, dated to the first failed check, and Internet Restored after two good checks in a row. A shorter drop leaves no entry.

Does the report prove my ISP was at fault?

No. Each verdict is an inference from which checks answered, so it says what the outage looks like from your network, such as that your router answered and the first hop past it did not. It is dated evidence you produced, to support a complaint, not a ruling.

What does the log cost?

Running the agent is free, and so are its own pages, which show 30 days of outages, and its alerts to your own services. The outage log on your iPhone, the push when the line drops and the Internet Outage Report need PingKit Guardian: $2.99 a month or $24.99 a year on iPhone, with a 1-week free trial.

Will a speed test from a Pi on Wi-Fi count against my ISP?

No. A test over Wi-Fi, or a wired test that reached 90% of the monitor's own link speed, is labelled as limited by this monitor's connection and left out of the report's figures, because it measured the monitor's link rather than your line.

Pair your monitor

Download PingKit, open Agents and tap Add an Agent for your code. Running the agent is free.

Download PingKit Free

Related Articles