Cron Monitoring Setup Guide

It's easy to monitor any kind of cron job with Cronitor. You'll be alerted if anything goes wrong with your job, including:

  • The job does not start on schedule
  • The job fails or crashes unexpectedly
  • The job runs longer than expected

How to Create a Cron Monitor

There are three common ways to create cron monitors.

  1. Install the CronitorCLI to automatically add monitoring to your crontab files.

    If you are monitoring cron jobs on Linux, BSD or MacOS our CLI will detect the crontabs on your system, and will walk you through adding monitoring as desired. It will automatically create the monitors and make the required modifications to your crontab files.

  2. Use the web dashboard to create individual monitors.

    Our web dashboard is an easy to use interface, and creating new monitors can be done quickly by anyone with a Cronitor account.

  3. Integrate with our Monitor API to programatically create monitors.

    For more advanced use cases, such as adding Cronitor to provisioning or deployment scripts, we offer an easy to use REST API as well as open-source API clients for many popular languages.

  1. Install CronitorCLI  (it's easy, promise).
  2. Run cronitor discover to find cron jobs and import them into Cronitor.
    • Use the auto-generated cron job names or use the interactive prompt to create something more memorable.
    • Discover will always find cron jobs in your user crontab. If run with elevated privileges, jobs in the system crontab and drop-in directory are also imported.

    Tip:You can re-run discover at any time to find new cron jobs or change names.

  3. You're done! All of the monitors will appear in a pending state on your account dashboard. As your jobs run the corresponding monitors will become active and start reporting activity.
  1. From the Cronitor dashboard, click the button to create a new monitor, and select the monitor type that bests matches your system cron.

    Tip:This is important because standard cron uses a 5 digit syntax, e.g. * * * * *, while some systems like Java Cron (Quartz/Spring) and AWS Scheduled Events support 6 digit cron expressions. In Java the extra * represents seconds, while on AWS it is years!

  2. Paste the schedule expression of your cron job into the 'Cron expression' field, and select the timezone of your server.

    If needed, adjust the grace period for this job. If your job fails to start or complete, Cronitor will wait the duration of the grace period before sending an alert.

    Tip:Server Timezone can be configured account-wide from the settings page.

  3. Give the monitor a descriptive name like Offsite Database Backup. You can optionally add tags to help you organize your monitors.
  4. You're done! Your monitor will be assigned a unique ping url and be placed in a pending state. Monitoring will begin when the first ping is received.

    For production usage, read the integration guide to learn more about using CronitorCLI, one of our language SDKs or just plain old curl to send pings when your job runs.

    To test things out, enter the ping url in your browser (replace d3x0c1 with your code), and ping https://cronitor.link/d3x0c1/run followed by https://cronitor.link/d3x0c1/fail to simulate a job that started and then exited with an error.

  1. Copy your API key from your settings page.
  2. Use cURL or one of our open-source API clients to make a POST request.

    curl -X POST https://cronitor.io/v3/monitors -u <API-KEY>: -d '{
        "name": "Database Backup",
        "type": "scheduled_task",
        "rules": [
            {
                "rule_type": "not_on_schedule",
                "value": "0 */3 * * 1-5"
            }
        ]
    }' -H "Content-Type: application/json"
    

    Tip: Complete documenation for our Monitor API can be found here.

  3. You're done! Your monitor will be assigned a unique ping url and be placed in a pending state. Monitoring will begin when the first ping is received.

    For production usage, read the integration guide to learn more about using CronitorCLI, one of our language SDKs or just plain old curl to send pings when your job runs.

    To test things out, enter the monitor's ping url in your browser, and ping https://cronitor.link/d3x0c1/run followed by https://cronitor.link/d3x0c1/fail to simulate a job that started and then exited with an error (replace d3x0c1 with your code).

How to Configure Alert Recipients

Cronitor can send alerts via many different channels, including: Email, Slack, PagerDuty, Microsoft Teams, SMS, webhooks and more.

Notification lists are configurable sets of channels that are attached to your monitors. When a monitor fails or recovers, an alert will be sent to every channel/recipient on the attached list. You can create or modify a list from the Notification Lists section of your settings page.

In the monitor's edit form locate the Alert Receipients panel. You may choose to add a notification list or add channels/recipients directly (or both).

Specify alert recipients adding a notifications object to your monitor JSON as shown below. Notification lists are attached using the template key. For complete list of options see our API docs.

curl -X POST https://cronitor.io/v3/monitors -u <API-KEY>: -d '{
    "name": "Database Backup",
    "type": "cron",
    "rules": [
    {
    "rule_type": "not_on_schedule",
    "value": "0 */3 * * 1-5"
    },
    ],
    notifications: {
    templates: ['devops-emergency'],
    slack: ['https://hooks.slack.com/2af3bvbnjwg9882']
    phone: ['+1555-555-5555']
    }

    }' -H "Content-Type: application/json"
            

Tip: When your Cronitor account is created a list named "Default" will automatically be created, and your email address will be added to it. When no list is specified the default list will be used.

How to Customize Duration Alerts

Cronitor uses the performance history of your job to detect anomalies in runtime. Our prediction algorithm grows more precise as we learn more about your job performance but it won't work perfectly for every job.

If you are receiving Running longer than expected alerts earlier than you would like, you can set a threshold duration for the job:

In the monitor's edit form locate the Alert Preferences panel and select Alert if this job runs longer than.

Specify a duration alert threshold by adding a ran_longer_than rule along with the not_on_schedule rule.

curl -X POST https://cronitor.io/v3/monitors -u <API-KEY>: -d '{
"name": "Database Backup",
"type": "cron",
"rules": [
{
    "rule_type": "not_on_schedule",
    "value": "0 */3 * * 1-5"
},
{
    "rule_type": "ran_longer_than",
    "value": 5,
    "time_unit": "minutes"
},

]
}' -H "Content-Type: application/json"
            

Nota Bene: With less data available on a new monitor we use a wider implied grace period and we will not send Running longer than expected alerts until the job has completed successfully at least once.

How to Customize Failure Tolerance Alerts

By default Cronitor will alert you every time we detect a problem. If you can tolerate a few failures, and do not wish be alerted each time, you can set the failure tolerance threshold of your monitor. You will be sent an alert when the number of consecutive failures exceededs the threshold.

In the monitor's edit form locate the Alert Preferences panel and select Failure Tolerance. Choose "Only send an alert if there is a persistent problem". Set the failure tolerance as desired.

Specify failure tolerance by adding the key tolerated_failures to your monitor's JSON object. The value is the threhold number.

curl -X POST https://cronitor.io/v3/monitors -u <API-KEY>: -d '{
"name": "Database Backup",
"type": "cron",
"tolerated_failures": 5,
"rules": [
{
    "rule_type": "not_on_schedule",
    "value": "0 */3 * * 1-5"
}
]
}' -H "Content-Type: application/json"
            

Adding Cronitor to Your Cron Jobs

For Cronitor to alert you when something goes wrong with your job a small amount of integration work is required to tell Cronitor when your job runs and completes or fails.

If you are monitoring traditional cron jobs the easiest way to do this the CronitorCLI. Running cronitor discover will add the integration for you automatically.

If you do not want to install the CLI, or you are not using crontab, you can integrate with Cronitor by instrumenting HTTP pings that correspond to the job running and completing. This can be done with curl as in the example below, or any http library. Cronitor's SDKs make it easy to integrate Cronitor with a number of popular languages.

Integrate with CronitorCLI (recommended)

CronitorCLI is the recommended way integrate your task or command with Cronitor. CronitorCLI is available for Linux, Windows and MacOS. The cronitor exec command will ping Cronitor when your task runs, completes or fails and reports your job duration and exit code.

Integrate without installing software

By making simple http requests to https://cronitor.link/d3x0c1 when your task runs, completes or fails Cronitor will be able to alert you when something goes wrong.

· ping https://cronitor.link/d3x0c1/run before your job runs

· ping https://cronitor.link/d3x0c1/complete after your job completes

Cronitor works anywhere that can make an outbound connection. Ping from a cron job or worker using curl, or integrate using any modern programming language, or monitor systems and services that can make http requests.


Learn More

Integration Guide Using CronitorCLI Ping API Guide

Invoke your command with CronitorCLI (recommended):

# m h dom mon dow   command

0 1 * * * cronitor exec d3x0c1 /path/to/mysqlbackup.sh

Invoke your command with the Cronitor Bash script:

# m h dom mon dow   command

0 1 * * * CRONITOR_ID=d3x0c1 cronitor /path/to/mysqlbackup.sh

Or, use Cronitor without installing software:

# m h dom mon dow   command

0 1 * * * curl https://cronitor.link/d3x0c1/run -m 10 ;  /path/to/mysqlbackup.sh && 
curl https://cronitor.link/d3x0c1/complete -m 10
Ping Cronitor before and after your job using CronitorCLI
#!/usr/bin/env bash
cronitor ping d3x0c1 --run
/path/to/do_things.sh
cronitor ping d3x0c1 --complete
Or, use Cronitor without installing software
#!/usr/bin/env bash
curl https://cronitor.link/d3x0c1/run -m 10 || true
/path/to/do_things.sh
curl https://cronitor.link/d3x0c1/complete -m 10 || true
Ping Cronitor before and after your job using Requests
import requests
requests.get(
   'https://cronitor.link/d3x0c1/run',
   timeout=10
)

# Application Code Here

requests.get(
   'https://cronitor.link/d3x0c1/complete',
   timeout=10
)
The same integration using urllib2 in the Python standard library
from urllib2 import urlopen
try:
  urlopen('https://cronitor.link/d3x0c1/run', timeout=10)
except Exception:
    pass

# Application Code Here
try:
  urlopen('https://cronitor.link/d3x0c1/complete', timeout=10)
except Exception:
    pass
Report failures to Cronitor
from urllib2 import urlopen
try:
  # Application Code Here
except Exception e:
    try:
      urlopen('https://cronitor.link/d3x0c1/fail?msg=' + e, timeout=10)
    except Exception:
      pass
Ping Cronitor before and after your job using OpenURI
require 'open-uri'
open(
   'https://cronitor.link/d3x0c1/run',
   :read_timeout=>10
)

# Application Code Here

open(
   'https://cronitor.link/d3x0c1/complete',
   :read_timeout=>10
)
The same integration using Net::http in the Ruby standard library
require 'net/http'
begin
    Net::HTTP.get(URI.parse('https://cronitor.link/d3x0c1/run'))
rescue Exception => e
end

# Application Code Here

begin
    Net::HTTP.get(URI.parse('https://cronitor.link/d3x0c1/complete'))
rescue Exception => e
end
Ping Cronitor before and after your job using file_get_contents
file_get_contents('https://cronitor.link/d3x0c1/run');
# Application Code Here
file_get_contents('https://cronitor.link/d3x0c1/complete');
The same integration using curl
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://cronitor.link/d3x0c1/run',
  CURLOPT_TIMEOUT => 10,
));
curl_exec($curl);

# Application Code Here

$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://cronitor.link/d3x0c1/complete',
CURLOPT_TIMEOUT => 10,
));
curl_exec($curl);
Cronitor OSS Libraries

Cronitor users have created a number of excellent open source libraries to make it easier to integrate Cronitor with your systems and automate the process of managing your monitors.

Libraries are available for Java, JavaScript, Ruby, PHP, Elixir, and more. See the whole list: Cronitor Open Source Libraries

Tip:Our Cron Integration Guide has more examples and an overview of our Ping API.

Frequently Asked Questions

  • What if my cron job starts after a random delay, like anacron?

    If you don't expect your job to start immediately at the scheduled time, expand the grace time on your monitor. Ensure your grace period exceeds any intentional or expected delay.

  • How do I determine my server timezone?

    On Linux and MacOS, use timedatectl or date to determine the current timezone locale. On Windows, use tzutil /g. Timezones can be set per monitor, and an account-wide default is available on the account settings page.