Crontab Scheduling

An alternative to interval scheduling is to use a crontab expression.

This triggers the monitor whenever the current time matches the provided crontab value.

For example, a monitor set to the crontab 0 3 * * * would fire at 3am every morning, as that is the only time at which the minutes equal 0 and the hours equal 3.

We use the standard crontab format, as per the original specification, but do not support any of the vendor-specific extensions. See below for more details on the expected format.

There is also a table of common values that you can use or adapt to your needs.

We highly recommend reading the section on potential gotchas, to be aware of a couple of possibly-unintuitive side effects of this scheduler.

Expression Format

A crontab expression has five components separated by space. For example, * * * * *, which would trigger every minute on the minute. Specifically, the syntax is:

<MINUTE> <HOUR> <DAY_OF_MONTH> <MONTH> <DAY_OF_WEEK>

Each component has a range of acceptable values, which are given in a table below.

Each item can use * to represent all values, or a comma-separated list (e.g. 1,18,23). Each entry on the list can also be a range (e.g. 4-17 to represent all values between 4 and 17, inclusive).

Optionally, each item can include a step filter, defined by a slash followed by a number. This only allows values that are also a multiple of the filter (e.g. */5 for 0, 5, 10, etc.)

Lists, ranges, and filters can be combined. For example, 6,10-21/3 would be equivalent to 6,12,15,18,21.

Component Ranges

For <DAY_OF_WEEK>, both 0 and 7 can be used to represent Sunday. This offers better compatability with different implementations.

Common Values

Potential Gotchas

Delays & Cancellation

There is a subtle difference between how scheduling works with intervals and crontabs. An interval schedule sets the time between the start of each execution, whereas crontabs specify the exact time at which it should start.

This usually achieves a similar effect, but a notable difference occurs when resuming an existing monitor. To illustrate it, let us consider an example.

Monitor A is set to run on a 5-minute interval. It is created at 13:05:00 - that is, exactly 5 minutes past 1pm. It runs immediately, and then again at 13:10:00 and 13:15:00. At 13:15:46 the monitor is manually paused.

If it is resumed before 13:20:00 - the next potential run time - it will execute then as planned. It will be as if it was never paused - no execution was delayed or cancelled. However, if it is still paused at 13:20:00 then it will not run again until resumed.

This occurs, and the monitor is not resumed until 13:21:37. It then runs immediately as the previous execution was more than 5 minutes ago, which is the configured interval. The next run will then be 13:26:37, then 13:31:37, and so on.

We can see that there is a permanent change to the schedule. The interval setting is still applied consistently - subsequent checks are scheduled 5 minutes after the start of the last - but the exact execution times have slipped.

Let us now consider the case of a crontab timetable.

Monitor B is set to run with a crontab expression of */5 * * * *, which means to trigger every 5 minutes, on the minute. It is created at 13:05:00, as before, and runs immediately as 13:05:00 matches the crontab expression.

The monitor next runs at 13:10:00, then 13:15:00. At 13:15:46 the monitor is manually paused, as before.

If it is resumed before 13:20:00 - the next potential run time - it will execute then as planned. It will be as if it was never paused - no no execution delayed or cancelled. However, if it is still paused at 13:20:00 then it will not run again until resumed.

Up until now, the behaviour has been identical to the interval monitor, but we are about to diverge.

As before, it is not resumed until 13:21:37, so the 13:20:00 execution was missed. Unlike with the interval schedule, Monitor B does not run immediately. The skipped execution is simply lost, and the monitor does not execute again until 13:25:00, then 13:30:00, and so on.

There has been no permanent change to the schedule, but a check instance was skipped.

In short, crontab-controlled jobs will only ever fire at the scheduled time. If the monitor cannot execute at that time (i.e. because it is paused), the slot is lost. No delayed or catch-up checks are performed.

Server Clocks

All of our monitoring servers are configured for UTC, and the software evaluating crontab expressions will similarly compare them using this timezone.

We use Google Public NTP to provide our time data. This service prevents leap second-related inconsistencies by smearing any time differences over a period of 24 hours. Thus, our clocks are up to 500 milliseconds away from true (UTC) time during the 12 hours either side of a leap second.

As with interval scheduling, you should be aware that the actual time a monitor check beings may be a few seconds after the scheduled time. This is due to a variety of factors, most notably network latency.

The delay is usually only a few milliseconds, and we guarantee to never start before the scheduled time (subject to the leap smear exception noted above).

We are not aware of any situation in which any of these timing details has caused a problem, but we mention them here for the sake of transparency.