// Using WellKept
Monitors
Uptime, keyword, certificate and domain checks, and when each opens an incident.
What a monitor is#
A monitor checks something from outside your server, the way a visitor or a browser would see it. The agent tells you what is wrong on the server. Monitors tell you what the world sees. A site can be up while its agent is offline, and the other way round, so the two raise different things: a finding for the server and an incident for the site.
Checks run from one location today.
The five types#
| Type | What it checks | How often |
|---|---|---|
| HTTP | Fetches the URL and checks the status is in the healthy range (200 to 299 unless you change it). | Every 1, 5 or 15 minutes |
| Keyword | As HTTP, and the page must contain, or must not contain, a word or phrase. For a page that answers but is wrong. | Every 1, 5 or 15 minutes |
| SSL certificate | Reads the certificate and counts the days left. | Every hour, 6 hours or day |
| Domain expiry | Reads the registration date from the registry (RDAP). | Daily |
| Cron heartbeat | Waits for one of your jobs to call a secret URL, and notices when it stops. | You say how often it runs |
An HTTP or keyword check follows up to five redirects and checks every hop. You choose a timeout between 5 and 30 seconds. A certificate that cannot be verified counts as a failure for these two types, and the message says so.
Incidents#
An HTTP or keyword monitor opens an incident after two failed checks in a row, so one dropped packet does not wake anybody. A cron heartbeat opens one after a single missed ping, because its grace period already does the waiting. The incident resolves on the first check that succeeds, or the next ping. Incidents always alert at high severity, whatever the hour, and you can acknowledge one so the team knows someone is on it.
Response times are charted for each monitor, with the average, the slowest and the 95th percentile, and uptime for the last day and week. Raw results are kept for 7 days and hourly summaries for as long as your plan keeps history.
Certificate and domain expiry#
These two types open a finding, not an incident, because there is nothing to resolve until someone renews.
- You choose how many days of warning you want: up to 90 for a certificate and up to 180 for a domain.
- Below that number of days a finding opens at medium severity. A certificate under 3 days or a domain under 7 days is high.
- It clears when the days left climb back above your number.
- If a check cannot read the dates (no connection, a registry that is down, a top-level domain with no RDAP service), nothing changes. The existing finding is held, and a domain check that cannot tell is "unknown", never a failure.
A monitor that is linked to a site on one of your servers also shows its findings on that server's page.
One limit to know about: the certificate monitor reads the certificate without checking that it is valid for the name or issued by a trusted authority. It reports expiry, not trust.
Cron heartbeats#
A cron heartbeat watches a job instead of a site. It is for the backup, the certificate renewal or the report that runs on a schedule, and that nobody notices when it quietly stops.
- Add a monitor, choose Cron heartbeat, and say how often the job runs and how much grace it gets.
- The monitor page shows a ready-made line. Put it at the end of the job with
&&, so it only calls the URL when the job succeeded:
/usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 -o /dev/null https://your-wellkept-address/ping/wk_ping_...
- A new heartbeat waits for its first ping. Nothing alerts before the job has run once.
- If no ping arrives within the period plus the grace, an incident opens at once and alerts at high severity as "missed its schedule". The next ping resolves it.
- Give a job that runs every few minutes a few minutes of grace. Give a daily job at least an hour, so a slow run or a clock change does not raise a false alarm.
- While a heartbeat is paused, pings are accepted but ignored, so pausing never makes the job fail. After you resume it, the clock starts again at the next ping.
- The address is a secret and says only "I ran". Keep it out of public repositories. New URL on the monitor page replaces it, and the old one stops working at once. Each URL accepts ten pings a minute.
- Pings are kept like checks, for 7 days, and a heartbeat counts against your monitor limit.
Limits#
Each plan sets how many monitors an organisation can have: see Plans and billing. Paused monitors count against the limit. A monitor suspended because a plan ended does not.
Private addresses#
A monitor target must be a public address. A name that resolves to a private, loopback or link-local address is refused when you save and again at every check, because a name can be re-pointed. The same applies to every redirect.
Checks identify themselves as WellKept-Monitor/1.0, so you can allow them in a firewall or recognise them in a log.