Cron Monitoring Integration Guide

Integrating with Cronitor is easy, and can be done in just a few minutes by anyone familiar with a command prompt and HTTP requests.

This guide assumes familiarity with our Cron Job Setup Guide. If you have not yet done so, please read that guide to learn how to create and configure a cron job monitor.

Integration Overview

In order to track the status of your cron job, Cronitor needs to know when your job runs, completes or fails. This is done by sending telemetry pings to Cronitor from your system.

Every monitor you create will have a unique ping URL. Making requests to the ping URL's different endpoints report the status of your job to Cronitor. Below are the three basic endpoints and their meaning.  See our Ping API guide for a complete API reference.

  • https://cronitor.link/d3x0c1/run

    The job has started running.

  • https://cronitor.link/d3x0c1/complete

    The job has completed successfully.

  • https://cronitor.link/d3x0c1/fail

    The job has failed.

Tip: Cronitor provides SDKs to abstract & simplify these calls for you.

Adding Cronitor to Cron Jobs

The CronitorCLI's cronitor discover command finds your crontab files, guides you though creating monitors, and automatically adds the required integration to your crontab file.

You can also modify your crontab file by hand. The examples below show the three most common ways of completing the integration.

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

Integrating with Cron-like Task Schedulers

Cronitor is easily added to cron-like schedulers such as Java Cron, NodeCron, Laravel Scheduler, Celery and more.

The most common approach to adding Cronitor to these types of task schedulers is to use our open-source SDKs to embed the telemetry pings within your scheduled jobs directly.

The example below uses the popular NodeCron and cronitor-js to demonstrate this type of integration.

var cron = require('node-cron');
var Cronitor = require('cronitor')

cron.schedule('*/5 * * * *', () => {
  var monitor = new Cronitor({monitorId: d3x0c1})
  monitor.run()
  console.log('running a task every five minutes');
  monitor.complete()
});

Tip:Laravel Scheduler provides task hooks for sending telemetry pings. If you are a Sidekiq user, the cronitor-sidekiq gem adds this for you.

If you are using Java Cron (Quartz/Spring Scheduler) or AWS Scheduled Events it is important that you specify this when creating your monitor as both use 6 digit cron expressions. See our Cron Setup Guide for more details.

Enabling Ping Authentication

For simplicity, Cronitor does not authenticate Ping API requests by default. If you wish to add this additional security measure to your account, it can be activated from your account settings.

If you're using CronitorCLI, save your Ping API key to your configuration file using cronitor configure --ping-api-key <KEY> (root or sudo access required), or set the CRONITOR_PING_API_KEY environment variable.

Cronitor's SDKs all support setting a Ping API key as well. If you're sending pings using curl or a native HTTP client, provide the key via an auth_key query parameter, e.g.

curl https://cronitor.link/d3x0c1/run?auth_key=<API-KEY>

Nota Bene: Ping API requests will always return 200/OK, but once Ping Authentication is enabled, Cronitor will not record your pings unless a valid api key is included in the request.

FAQ & Tips

  • A ten second timeout is used in our examples but we do not expect pings to take nearly that long. A lost ping will often mean a false alarm so we use a long timeout to avoid that. It's not a magic number and certainly should be tweaked if your use-case demands it. We maintain a 95th percentile time of sub one second.
  • We recommend using https to keep your ping URL private and server traffic encrypted, but you may also use http. If you are troubleshooting SSL errors from your cronitor ping, it's commonly a timeout issue unrelated to SSL. Unencrypted pings must be made to cronitor.link. Ping requests to cronitor.io are deprecated and redirect unencrypted traffic to https.
  • Your monitor is not initialized, and alerts will not be sent, until your first ping.
  • Ping endpoints support both http GET and POST, though any POST body is ignored.
  • If brevity is important to you, you can abbreviate endpoints to their first initial:
    • https://cronitor.link/d3x0c1/r
    • https://cronitor.link/d3x0c1/c
    • https://cronitor.link/d3x0c1/f