Integration guide

Cronitor integration for cron job and heartbeat monitors is easy and can be done in just a few minutes by anybody comfortable with a command prompt. Before reading this document, you might find it helpful to read How Cronitor Works and Understanding Ping URLs.

Choosing an Integration Path

To send alerts, Cronitor must know when your job starts running and when it completes successfully. You will report these events to Cronitor by making requests to your monitor's unique Ping URL.

The simplest and most popular way to report these events is by integrating your Cronitor pings directly within crontab. You can see an example below. The downside to this -- making your crontab more difficult to read -- can be improved with a wrapper script, but if it's a problem for you, you may want to consider other integration options. There are many alternatives: because a ping is just a simple HTTP GET request, you can integrate Cronitor anywhere. The annotated examples below demonstrate simple integrations using common HTTP libraries in a few popular languages.

Integration Examples

How integration works

By making simple HTTP requests to https://cronitor.link/d3x0c1 you will provide Cronitor the information needed to continuously evaluate the rules you have added. When a rule is violated you will usually be notified within 1 minute.

Cronitor works everywhere: ping from a command line, any modern programming language, or from tools and services that can make HTTP requests. There are examples here you can paste and use directly.

Learn More

Integration Guide Ping URLs & Endpoints

Ping Cronitor before and after your job using Curl:

# 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

Report failures and trigger on-demand alerts:

# m h dom mon dow   command
0 1 * * * /path/to/mysqlbackup.sh || curl https://cronitor.link/d3x0c1/fail -m 10

Ping Cronitor before and after your job:

#!/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

On paid accounts, trigger failure using the on demand alert API:

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

Understanding URL placement

A reliable monitor is a 3-legged stool: the rules you create, the endpoints you ping, and when you choose to ping them. All three must be done properly for Cronitor to provide reliable and accurate alerts.

Covered in detail in our Understanding Ping URLs guide, each monitor you create is assigned a unique ping URL. Each ping URL exposes endpoints you will use to tell Cronitor the status of your job: /run, /complete, /fail and /pause.

/run

Your /run pings should be made when your job starts. For accurate time tracking, the request should be made as close to the true beginning of your job as possible. This event and the corresponding Run Endpoint Not Pinged In rule are used to report that the job has started, not necessarily completed successfully.

/complete

Your /complete pings should be made when your job completes successfully. For accurate time tracking, the request should be made as close to the true end of your job as possible. This event and the corresponding Complete Endpoint Not Pinged In rule are used to report that the job has run successfully. If you only create one rule on your monitor it should probably be a Complete Endpoint Not Pinged In rule.

/fail

Ping the /fail endpoint to report a fatal error or failure of your job, or to send customized alerts with a custom alert msg. Alerts are sent immediately on-demand when the ping is processed, regardless of the monitor's defined rules. The most common place for /fail pings is within exception handlers or after your job returns a non-zero exit code.

/pause

You may want to pause monitoring temporarily after /fail pings to prevent duplicate alerts from any Complete Endpoint Not Pinged In or Ran Longer Than alerts. If you are not using the on-demand failure endpoint, you may not have any reason to integrate /pause into your code. Remember, all Cronitor alert emails include simple 1-click pause links.

Pro-tips & Points of Interest

  • In all of our examples, we try to ensure that your /run ping can never interfere with your job. This is done in Curl examples by chaining commands carefully, in our language integrations by wrapping the requests in try/catch blocks, and in both by specifying timeouts.
  • 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. Our goal is a 90th percentile time of 1.0 second, but in the modern world of NTP, we receive significant traffic spikes at the top of the hour and requests are sometimes queued.
  • 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. Note: unencrypted http pings must be made using the cronitor.link hostname. Ping requests to cronitor.io are deprecated and will not accept unencrypted traffic.
  • Your monitor is not initialized, and alerts will not be sent, until your first ping. It's best to avoid the temptation of loading the URL in a browser first: we promise it will only return an empty 200/ok.
  • Ping endpoints support both http GET and POST.
  • If brevity is more important to you than clarity, you can abbreviate endpoints to their first initial: /r, /c and /f

Deprecated Endpoints

To more clearly align rules and endpoints, /b and /e ping endpoints are deprecated and will be mapped internally to /run and /complete, respectively. Similarly, you may have been given a URL without any endpoint specified. This URL was always treated as a /b "begin" ping. We've deprecated these requests and discourage them. To maintain backwards compatibility we will continue to map these requests to /run.

If you are an early Cronitor user with a "not run in" rule and you modify your integration to ping /run before your job and /complete after, you may want to change your "not run in" rules to "not completed in". A "not run in" rule uses /run pings, which you will now send before the job runs. A "not completed in" rule uses the /complete pings that will only be sent if your job completes successfully.