Monitors: know when background work fails or never runs
Monitors watch scheduled jobs, queues and workers: a run that fails, runs too long, ends with an unknown result or never happens opens an incident.
On this page
Errors tell you when code throws. They cannot tell you that a nightly job never started, that a queue worker died, or that an import ended without anyone knowing whether it finished. A monitor watches one piece of background work and opens an incident when a run goes wrong — including the run that never happens.
Prefer no SDK at all? A ping URL monitor watches any cron job or timer with one secret URL, and keeps alerting even when your app or node is down.
| Check-in monitor | Ping URL | Uptime check | |
|---|---|---|---|
| Who sends | Your job, through the SDK or HTTP | Your job, with one HTTP call | Belvador's probes call your URL |
| Catches | Missed, failed and too-long runs | Missed, failed and too-long runs | A site or port that is down, slow, wrong or has an expiring certificate |
| Judged by | Your node | Belvador's monitor service | Belvador's monitor service, from three regions |
| While your node is down | Shows Not observable; a real miss is reported late | Still alerts | Still alerts |
How a monitor works#
Your job sends a short check-in to Belvador when it starts and when it ends. Your node compares those check-ins with what the monitor expects and decides, every 15 seconds, whether each run was healthy.
A check-in is not an error event and never creates an issue. Errors your job throws still become issues as usual, linked to the run they happened in.
Monitors live per project. The slug (for example
nightly-invoices) is how your code names the monitor; it cannot change later.Check-ins come from servers, workers, CI or a shell. Browsers cannot send them.
Three kinds of schedule#
| Kind | Use it for | When a run is late |
|---|---|---|
| Cron schedule | Jobs on a calendar: 0 2 * * * = every day at 02:00, in the time zone you choose | No check-in by the scheduled time plus the grace period |
| Every N minutes/hours | Workers and heartbeats that should report regularly | No check-in within N after the last one, plus the grace period |
| When something happens | Work started by an event (a webhook, a button) | Never late — only failures and timeouts count |
Cron schedules follow the time zone's clock changes: a 02:30 job on the night the clocks skip 02:30 is due an hour later, at 03:30, and a repeated hour runs once. The create form shows the next five deadlines so you can check this.
What a run can end as#
| Result | Meaning | Counts as |
|---|---|---|
| OK | The job finished its work | Healthy |
| Skipped | The job ran but had nothing to do (your code said so) | Healthy |
| Failed | The job reported an error or threw | Failing |
| Timed out | It started but did not finish within the maximum runtime | Failing |
| Missed | No check-in arrived in time | Failing |
| Outcome unknown | The job ended but could not tell whether its work took effect — for example a payment provider timed out after the request was sent | Needs review |
A retried attempt belongs to the same run: three attempts where the last one succeeds is one healthy run with three attempts, not two failures.
Limits per monitor#
| Setting | Default | Range |
|---|---|---|
| Grace period — how late a check-in may arrive | 5 min | 1–1440 min |
| Max runtime — after this a started run is timed out | 30 min | 1–10080 min (7 days) |
| Failures before an incident | 1 | 1–720 |
| Successes before recovery | 1 | 1–720 |
| Environments to watch | production | up to 10 |
Environments#
A monitor watches the environments you list (default production). Check-ins from other environments — staging, development — are still recorded and shown in their own tab, but a missed run there never opens an incident. A laptop that is switched off at night therefore never pages anyone.
Incidents and alerts#
One incident opens when a monitor starts failing and closes when it recovers. The default alert rule Monitor problems sends exactly one message when it opens and one when it closes, to every active destination of the workspace — see Alerts. You can mute a single monitor: incidents still open on the page, but no message is sent.
Needs review is amber, not red: someone has to check whether the work happened. Open the run, check your system, then press Mark as reviewed.
When Belvador cannot see#
If your node is offline, is catching up after a reconnect, or check-ins were rate limited, the monitor shows Not observable instead of Missed. Belvador never marks a run as missed for a time it could not watch. After the node is back it waits up to 10 minutes for check-ins buffered at the edge before judging, so runs that happened while it was away appear at the right time; a run that really did not happen is then reported with "detected late".
Your app is never slowed down by this: check-ins are sent in the background with a small queue, and a Belvador outage only means check-ins are dropped and counted.
Next steps#
Add monitors with the Belvador SDK (TanStack Start, Cloudflare Workers)
HTTP check-ins for shell, CI and any language
Other Sentry SDKs (Python, Node.js, …)
Spotted something wrong or missing? Tell us: hello@belvador.dev