5.2Interval and cron schedules

A heartbeat uses one of two schedules. The cron expression field decides which one.

cron expression	Schedule	Fields shown
Empty	Interval: the job runs every N minutes or hours.	expected every, grace periods
Filled in	Cron: the job runs at fixed times.	timezone, grace seconds

Interval#

An interval is the time between two runs. Use it for a job such as a worker that runs every 5 minutes. Leave cron expression empty. In expected every, enter a whole number and choose minutes or hours. The smallest value is 1.

Your plan's minimum still applies. If you go below it, the form shows Your plan checks at most every <N> seconds.

Cron#

A cron expression is the schedule part of a crontab line, for example 15 2 * * *. A crontab is the file that lists the jobs cron runs. Use a cron schedule for a job that runs at fixed times, such as 02:15 each night. Copy the same expression into cron expression.

obsrvly uses the standard five fields, in this order: minute, hour, day of month, month, day of week. A seconds field is not supported. These short forms also work: @hourly, @daily, @midnight, @weekly, @monthly, @yearly and @annually.

Expression	Runs
`15 2 * * *`	Every day at 02:15
`/10 * * *`	Every 10 minutes
`0 9 * * 1-5`	At 09:00, Monday to Friday
`30 3 1 * *`	At 03:30 on the first day of each month
`0 /6 * *`	Every 6 hours, on the hour

Timezone#

The timezone is the zone your schedule uses. Enter a standard name, such as Europe/Berlin, America/New_York or Asia/Kolkata. Leave it empty for UTC.

Get this right. A crontab's 02:15 is usually the server's local time, not UTC. Set timezone to the server's zone. A job at a fixed local time keeps that time when daylight saving time starts or ends.

If the form shows an error#

Message	What to do
`Five fields: minute hour day-of-month month day-of-week`	Enter exactly five fields, or a short form that starts with `@`.
`invalid input: invalid cron expression: …`	The rest of the message names the wrong field. Fix that field.
`invalid input: invalid cron expression: unknown timezone "<tz>"`	Use a standard timezone name, such as `Europe/Berlin`.
`Your plan checks at most every <N> seconds`	Choose a longer expected every.

Create a heartbeat through the API#

You can also create a heartbeat with the obsrvly API (chapter 13). Send the request with your API key.

Create a cron heartbeat

bash

API=https://www.obsrvly.com/api/gw/monitor/obsrvly.v1.MonitorConfigService
curl -X POST "$API/CreateHeartbeatMonitor" \
  -H "Authorization: Bearer obs_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Nightly backup", "cronExpression": "15 2 * * *",
       "cronTimezone": "Europe/Berlin", "graceSeconds": 1800}'

Field	Use
`name`	The monitor's name.
`intervalSeconds`	Interval in seconds. Required when `cronExpression` is empty. You can leave it out for a cron schedule.
`gracePeriods`	Grace for an interval schedule (5.3).
`cronExpression`	The cron expression. Leave it out for an interval schedule.
`cronTimezone`	Timezone name. Empty means UTC. Allowed only with `cronExpression`.
`graceSeconds`	Grace for a cron schedule (5.3). Ignored without `cronExpression`.
`alertChannelIds`	The alert channels to notify.

The response contains monitor and token. It does not contain the full ping URL. To build it, copy the URL of any heartbeat in the dashboard and replace the part after /heartbeat/ with the new token. The token is also in the monitor's settings as heartbeatToken.

API errors start with invalid input:. For example: interval_seconds must be > 0, or cron_timezone has no meaning without cron_expression. An interval below your plan's minimum is refused with a message that names the minimum.