Documentation

Monitors

A monitor is one thing you want watched and the rule for deciding whether it is healthy. There are thirty kinds. Most of them make a request from our network and judge the answer; two wait for something to arrive from yours, and four collect what your routers export to your own private probe.

The kinds

Web and network

Certificates and domains

Mail

Infrastructure protocols

These exist because a tcp check on the port proves almost nothing about them. An SMSC accepts TCP long after it stops binding anybody; a SIP stack can be wedged with the socket open; an XMPP server whose certificate expired still completes a TCP handshake.

Databases

Pro and above. A tcp check on 5432 proves that something accepted a socket, and every interesting database failure keeps the socket open: Postgres in crash recovery, a connection limit a leaking application has filled, a role whose password expired, a database that was renamed, a data directory that did not mount. So these open a connection, log in, and ask the server one trivial question.

None of them reads or writes anything. This is an availability check, not a synthetic transaction: give it an account that can do nothing but connect.

The credential is stored unencrypted, because the probe that runs the check is handed the configuration as it is. For that reason these five run only from a probe cleared for personal data — the same restriction snmp and smpp carry.

That means one of two places. Your own private probe, which is the one these checks are designed around: it runs on your hardware inside your network, so the configuration never leaves your infrastructure, and it is usually the only thing that can reach a database worth monitoring — a database behind a VPC, a private link or an allowlist is not reachable from anybody else’s network, ours included. Failing that, our own EU vantage points, for a database that genuinely is publicly reachable.

Containers

Pro and above. A check on a container’s published port answers for the proxy in front of it. A crash-looping container behind a restart policy is up for a few seconds at a time, a failing HEALTHCHECK leaves the port open, and an OOM kill followed by a restart looks like one slow request. The Docker engine knows all three.

Access to the Engine API is root on that host, so the endpoint and its client certificates are credentials, and this kind runs only from a probe cleared for personal data. A unix socket is opened only by a probe started with DOCKER_SOCKET_ENABLED=true, which is something you set on your own private probe beside your own engine and we never set on ours; anywhere else the check abstains rather than reporting your container down. A tcp:// or https:// endpoint with client certificates works from either.

Network traffic

Business and above. An uptime check tells you a link answers; it cannot tell you the link is saturated, that a backup job is flooding it at noon, or that traffic to your web tier quietly dropped to nothing. Your routers and switches already count all of that and can export it. These kinds collect that export and turn it into rates, a breakdown by protocol, and the busiest ports and addresses.

Every threshold is optional — a maximum bit rate, a minimum bit rate, a maximum packet rate. Above or below one is degraded. With none set, the monitor records and graphs traffic without alerting on a value. An exporter that stops sending for longer than you allow is down, and one sending the wrong protocol — sFlow at a NetFlow monitor — is down with a message that says so.

These run only on your own private probe. Flow export is UDP, which carries no authentication: a collector on our shared network would have to trust the sender’s address, which anybody can forge or claim. On a probe inside your network, the only routers that can reach it are yours. It also keeps your traffic records at home — they name the addresses of the people on your network, so the probe aggregates them where they arrive and sends us only the rates and the top-ten tables. Start the probe with FLOW_COLLECTOR_ENABLED=true, publish the UDP ports, point your routers at it, and choose that probe when you create the monitor.

Things that report to us

How often it runs

You choose an interval; your plan sets the floor. Free checks every minute, Starter every 45 seconds, Pro every 30, Business every 15, Enterprise every 5.

Four kinds have their own floor, regardless of plan, because the answer does not change minute to minute and asking more often would be noise and load on somebody else’s server:

Mail authentication, and actually sending mail

A mail_posture monitor reads SPF, DKIM, DMARC, MTA-STS and TLS-RPT out of DNS and tells you what is broken. That catches a record that rotted, and it cannot catch the thing those records are a prediction about: a domain can publish flawless SPF and send from a server that record disowns, publish a DKIM key and sign with a rotated one, or have a gateway rewrite a header and break a signature that was valid when it left.

Give the monitor a mailbox — an address, and SMTP and IMAP credentials for it — and it measures instead of predicting. Every hour it submits a message through your own outgoing server to our listener, which checks the SPF and DKIM of what actually arrived, and then replies into the mailbox so the next run can confirm over IMAP that your domain receives mail as well as sending it. Both legs have to complete. A domain that sends perfectly and has quietly stopped accepting mail is a real outage, and it is one that every send-only check in existence reports as healthy.

Two things worth knowing before you fill it in. The credentials are stored unencrypted and handed to the probe that runs the check — that is true of every monitor’s configuration, because the probe is the thing making the request — so a monitor with a mailbox only ever runs from inside the European Union, and never from our probes elsewhere. Use an application password where your provider offers one. And the reply we send is deleted from the mailbox as soon as it has been read, so the folder does not fill up.

An interval is not how fast you hear about an outage

This is the part worth reading twice. A single failed check does not open an incident. A monitor has to fail three times in a row — that is theconfirmations setting, and three is the default — before anybody is told.

It is not three times the interval, though. When a check fails, the next one is pulled forward rather than waiting out the full interval, so a five-minute monitor confirms an outage in well under fifteen minutes. A result can only ever make the next check sooner, never later.

Lower confirmations if you would rather be woken early and occasionally for nothing. Raise it for something you know flaps.

Checks rotate between locations

We check from several places, one per interval, rotating. Three vantage points on a five-minute monitor means each one sees it every fifteen minutes while the monitor is still checked every five.

That is what makes confirmation meaningful: three failures in a row are three failures seen from three different places, so a probe that simply cannot reach your server is harmless — the next region succeeds and the streak resets.

A failure while another location is fine is degraded, not down. Down should mean your site is unreachable, not that one vantage point cannot see it. It still counts as failing and an incident still opens, with degraded severity.

A firewall is not an outage

A site blocked in one location fails every check from there while working everywhere else. Counting that as downtime would make your uptime figure a statement about our routing rather than about your service.

So a region that has never reached a monitor is excluded from it after three failures. A region that used to reach it and no longer does keeps counting, permanently — because that is a real outage from there, and hiding it would be worse.

If the world changed around a site — a government block, a dropped route, a geo-gate added later — you can recalibrate a monitor from its page. That drops every region’s history for that one monitor, so current behaviour becomes the new baseline. It is per-monitor and deliberate, because measurement alone cannot tell a permanent block from a permanent outage.

Where checks run, and what we send there

Some vantage points are outside the EEA. A check whose configuration could contain personal data — a request header, a request body — only ever runs from inside it. That is enforced by the scheduler rather than by policy, and tested against a real database on every build. snmp, smpp and the five database kinds are confined the same way, because in all of them the credential is the protocol.

Untested is not a pass

For tls_audit, every probe has three outcomes rather than two: supported, refused, or untested. Node’s OpenSSL 3 compiles in neither RC4 nor 3DES, so those two families can never be offered from our fleet — and silence under those headings would read as “we looked and they are off”, which is a false all-clear on exactly the findings a TLS audit gets opened for.

Dependencies

Tell a monitor what it depends on — a database, a gateway, an upstream API — and when the dependency is down, the things behind it are marked as consequences rather than opening incidents of their own. One incident, not forty, and the page names the root rather than the symptoms.

Maintenance windows

Schedule a window and nothing pages anybody while it is open. Use it for a deploy you know will take the thing offline. By default checks still run and still record, so those minutes count towards uptime like any others — the window removes the alert, not the history. Turn off “keep checking” and nothing is checked while the window is open, which leaves a gap in the history rather than a dip. A window can repeat daily, weekly or monthly, and every occurrence holds alerts back, not just the first.

Pausing

A paused monitor is not checked and counts against nothing. It keeps its history, so pausing and resuming does not lose the record.