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 Telemetry Events guide for a complete API reference.

  • The job has started running.

    https://cronitor.link/p/:apiKey/nightly-job?state=run
  • The job has completed successfully.

    https://cronitor.link/p/:apiKey/nightly-job?state=complete
  • The job has failed.

    https://cronitor.link/p/:apiKey/nightly-job?state=fail

Tip: Cronitor provides SDKs for the Telemetry Events API.

Adding Cronitor to Cron Jobs

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 two common ways of completing the integration.

# Install CronitorCLI
curl -sOL https://cronitor.io/dl/linux_amd64.tar.gz
sudo tar xvf linux_amd64.tar.gz -C /usr/bin/
sudo cronitor configure --api-key <API-KEY>
# With CronitorCLI (recommended)
# m h dom mon dow   command
0 0 * * * cronitor exec nightly-job /path/to/executable

# Or without software
0 0 * * * curl https://cronitor.link/p/<API-KEY>/nightly-job?state=run -m 5 ; /path/to/executable && curl https://cronitor.link/p/<API-KEY>/nightly-job?state=complete
View on Github

CronitorCLI is the easiest way to monitor a crontab file.

Integrating with Cron-like Task Schedulers

Cronitor is easily added to cron-like schedulers such as Spring scheduled tasks, 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('cronitor')('cronitor_api_key');
cron.wraps(require('node-cron'));

cron.schedule('nightly-job', '*/5 * * * *', () => {
  console.log('running a task every five minutes');
});

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 JVM based 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.

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