Grace periods & states
A late check-in isn't always a problem — jobs jitter, queues back up, a run takes a little longer than usual. The grace period is how much lateness CronWarden tolerates before it treats a missed check-in as real and notifies you.
Grace period
The grace period is the single tolerance knob: how long a check-in may be late before the monitor is considered down and pages. If the next check-in doesn't arrive by the expected time plus the grace period, the monitor goes down and a critical Missed alert notifies your integrations.
While the grace is still running, the monitor shows late — a pending state on the dashboard, not a page. If the check-in arrives inside the grace, the late state clears silently and nothing was ever sent. This is what makes a single delayed run a dashboard blip instead of a notification.
CronWarden picks a sensible grace from the schedule when you create a monitor (roughly two missed runs on fast schedules, a fixed detection budget on slow ones), and you can override it. Raising the grace makes a monitor tolerate more lateness before paging; lowering it pages sooner. A job that runs every 5 minutes might tolerate 10 minutes of slack; a nightly backup might tolerate an hour.
Want a heads-up the moment a run is overdue, without waiting out the grace? Turn on Notify when late on the monitor (notifyOnLate in the API) — that opts the monitor back into a warning notification at the start of the late window.
The states
A monitor moves through a small set of states:
| State | Meaning |
|---|---|
| New | Created but hasn't checked in yet. |
| Up | Checking in on schedule. |
| Late | A check-in is overdue but still inside the grace window. |
| Degraded | Checking in, but a run tripped a warning — too fast, drifting, or a failed value check. |
| Down | A check-in was missed past its grace period, or the job reported a failure. |
| Paused | Monitoring is intentionally suspended; no alerts. |
Late is a pending state: visible on the dashboard, silent by default (turn on Notify when late for an early warning). Degraded is a warning — the job ran, but the run was wrong. Down is critical and pages. This split is what lets a slow night stay a dashboard blip while a genuine outage pages someone. See Alert types.
New monitors
A monitor that has never pinged follows its new-monitor policy:
- Wait for the first ping (default) — the monitor sits in New and never alerts until the job checks in once. Create monitors ahead of the jobs they watch without a page in between.
- Alert on the first miss — the schedule is armed the moment the monitor is created, so a first run that never checks in alerts. Use this when the job already exists and a deploy that failed to install the cron must be caught.
Either way, once the first ping arrives the policy is inert and normal monitoring applies.
Runs that start but don't finish
If a job checks in at /start but the matching success never arrives within the window, CronWarden raises a Start Missed warning — it knows the run began and stalled, which is different from a run that never started at all.