# monitor.heartbeat-check

A heartbeat (a cron job that pings the monitor on a schedule, judged by
`monitor.heartbeat`) as one check behind a status page component, so the
job can sit on the same page as the HTTP targets and feed
`monitor.component-state`, `monitor.incidents` and `monitor.uptime`.

| heartbeat state | check status | why |
| --- | --- | --- |
| `up`   | `up`       | pinged within its period |
| `late` | `degraded` | past due but inside the grace time: something is slow, nothing has failed yet |
| `down` | `down`     | past the grace time: the job has stopped |
| `new`  | null       | it has never pinged, so there is nothing to report |

## Why this shape

- **Late is not down.** The grace time exists because jobs run long; calling
  a late job down would page for exactly the case the grace time was set to
  absorb. healthchecks.io, which named these states, only alerts on down.
- **New is null, not up.** A heartbeat that has never pinged has proved
  nothing. Calling it up would show a never-deployed job as healthy on the
  status page; calling it down would page for a job that is not due yet. The
  caller leaves it out of the component's checks (and shows "awaiting first
  ping") until the first ping arrives.

## Errors

- `unknown heartbeat state: X`, for anything but `new`, `up`, `late` and
  `down` (case-sensitive; a `CheckStatus` such as `degraded` is refused).

## Sources

- healthchecks.io, "Configuring checks: period and grace time" (new, up,
  late, down; notifications only when a check goes down):
  https://healthchecks.io/docs/configuring_checks/