Monitors / Monitor cron jobs with push

Monitor cron jobs with push

Give a backup, a cron job or a script its own URL to call, and get alerted when the call does not arrive in time or reports a failure.

Every other monitor goes out and checks a service. A Push (heartbeat) monitor works the other way round: your job calls a URL when it finishes, and the monitor goes down when no call arrives in time. Use it for backups, cron jobs, scheduled scripts and anything that cannot be reached from outside.

Create a push monitor

Pick Push (heartbeat) in the Jobs & crons family of the Monitor protocol list. The Schedule card is replaced by two fields:

Field	Default	Range	Meaning
Expected every	86400 s	60 s to 30 days	How often your job runs. One day by default.
Grace period	3600 s	0 s to 7 days	Extra time allowed before an alert, for a job that runs late.

The form shows each value in a readable form, for example ≈ 1 day, and the deadline that results: without a call for Expected every plus Grace period, the monitor goes down.

Choose Create monitor. Nothing is contacted from Uptime Kotlin: the monitor waits for your job.

Get the push URL

Open the page of the monitor. The Push URL card gives the address to call:

Terminal

https://uptime.example.com/api/push/0aF3…

Choose Copy to copy it. The card also shows the Last call, the period expected with its grace, and the number of Calls received. Integration examples gives ready-made commands with your URL.

The token in the URL is the only protection: anyone who knows it can report for this monitor. Keep it out of public repositories. If it leaks, choose New URL: the old URL stops working at once, so update every job that calls it.

Use the public address of your instance. The URL is built from the address you use in your browser. Your jobs must be able to reach it, through your reverse proxy if you have one.

Call it from a job

Call the URL with GET or POST once the job succeeds. With cron, chain the call after the job with &&, so it only runs on success:

Terminal

0 2 * * *  /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 https://uptime.example.com/api/push/<token> > /dev/null

To report a failure right away, without waiting for the deadline, add status=down and an optional message:

Terminal

/usr/local/bin/backup.sh || curl -fsS -m 10 "https://uptime.example.com/api/push/<token>?status=down&msg=backup%20failed"

Parameter	Values	Meaning
`status`	`up`, `ok`, `success` (or nothing) `down`, `fail`, `failure`, `error`	The job succeeded, or failed.
`msg`	Free text, up to 500 characters	Shown in the logs and the alert. Encode spaces as `%20` in a URL.

The answer tells you what happened:

Answer	Meaning
`200` `{"ok":true}`	The call is recorded.
`200` `{"ok":true,"ignored":"monitor paused"}`	The monitor is paused: the call is ignored.
`400` `{"ok":false,"error":"status must be up or down"}`	`status` has an unknown value.
`404` `{"ok":false,"error":"unknown push token"}`	The URL is wrong, or it was replaced with New URL.

How the deadline works

The deadline is checked every minute:

Before the first call, the time counts from when monitoring started. The log reads Waiting for first ping, deadline in 1d 1h.
After a call, it counts from the last call: Last ping 3m ago, followed by the message of the call if there was one.
Past the deadline, the monitor goes down at once, without retries: No ping received for 1d 2h (expected every 1d).
A call with status=down puts the monitor down at the next check, a few seconds later: Job reported a failure 2s ago: backup failed.
The next successful call brings it back up right away, and the incident closes.

Pausing the monitor ignores calls. When you enable it again, the deadline starts over, so a job that did not run during the pause does not raise an alert straight away.

Set the grace period to the usual duration of your job, plus a margin: a backup that runs at 02:00 and takes 40 minutes calls the URL around 02:40.

Suggest a change on GitHub