Skip to content
Docs

Heartbeat

On this page
  1. How it works
  2. When is the next call expected?
  3. Settings
  4. Example
  5. Good to know

Most sensors go and check something. The Heartbeat sensor works the other way round: your job calls Onagre each time it completes, and Onagre opens an incident when the expected call does not come. Use it for what no one can check from the outside: a nightly backup, an import, a cron job, a worker that must keep running.

In the wizard: Scheduled job; as templates: Scheduled job, Nightly backup, Daily import or sync, Background worker. Requires a paid plan. No agent is involved.

How it works#

  1. Create the sensor: its schedule says when your job runs, its grace period how long it may take to report.
  2. Open the sensor's page: the Heartbeat endpoint card gives the URL to call, with a Copy URL button. The URL contains a secret: treat it like a password.
  3. At the end of your job — only when it succeeded — send an HTTP POST to that URL.
  4. Each call marks the sensor as up and sets when the next call is expected. If that moment passes without a call, the sensor goes down and an incident opens. The next call resolves it, even if the incident was acknowledged.

Monitoring starts with the first call: a new heartbeat sensor does not open an incident before your job has called it at least once.

When is the next call expected?#

Schedule Next call expected before Example
Interval (every N minutes or hours) the last call + the interval + the grace period A worker reporting every 5 minutes, grace 5 min: an incident opens after 10 minutes of silence.
Daily or Weekly the next scheduled run + the grace period A backup starting at 02:00, grace 2 h: each night's call must arrive before 04:00.

Times are in your organization's time zone (see Your profile).

Settings#

Setting Description
Check schedule When your job runs: an interval, or a daily or weekly time. Set the start time of the job, not its end.
Grace period How long after the expected run the job may still report, in minutes (up to 7 days). Use the longest normal duration of the job.

Example#

Nightly backup starting at 02:00, with a 2-hour grace period. At the end of the backup script:

Terminal
#!/bin/bash
set -e
/opt/backup/run-backup.sh
curl -fsS -X POST "https://app.onagre.io/heartbeat/<your-secret>"

With set -e, the call is only made if the backup succeeded: a failed backup and a backup that did not run at all both end in an incident before 04:00.

Good to know#

  • Call the URL from the job itself, after the work is done — not from a separate scheduler entry, which would keep calling even when the job fails.
  • One call every 10 seconds is accepted per sensor; a worker should report every few minutes at most.
  • A paused sensor stays paused when calls arrive.
  • If the URL leaks, anyone could keep the sensor up: create a new heartbeat sensor to get a new URL.
  • Each private agent also has an internal heartbeat that tells Onagre it is connected; it is managed with the agent and does not appear in your resources. See Public and private monitoring.