Integration guide

Cronitor integration for cron job and heartbeat monitors can be done in just a few minutes by anybody comfortable with a command prompt.

What integration is required

To send alerts when something goes wrong Cronitor needs to know when your task runs, completes or fails. Each monitor you create is given a unique Ping API endpoint to collect these telemetry events from your server. You can send telemetry pings from anything that can make an http request:

  • From the command line using CronitorCLI, curl, PowerShell, etc
  • Directly from your application code using any native http library or an open source Cronitor API client

Monitoring traditional cron jobs

If you are monitoring jobs in a crontab, using cronitor discover from CronitorCLI is the easiest way to automatically create monitors for each job and keep their schedule in sync with your server. Required integration is completed automatically by discover after you save the updated crontab. Read our guide on cron job monitoring for details.

Heartbeat monitoring

If you are monitoring a script or command on your server, using cronitor exec from CronitorCLI is the easiest way to send telemetry pings to Cronitor on success or failure.

  1. After creating a new heartbeat monitor from the dashboard or API, copy the unique code provided. This identifies the unique Ping API endpoint for this monitor.
  2. Update the invocation of your command to pass the command as an argument to cronitor exec, using the unique code provided in the previous step. In this example, d3x0c1 is the unique monitor code.

    Before, you are invoking logrotate directly:
    /usr/sbin/logrotate

    After integration, you are invoking logrotate using cronitor exec:
    cronitor exec d3x0c1 /usr/sbin/logrotate
When using heartbeat monitoring for workers, daemons, containers, etc you can invoke the CronitorCLI ping command or send pings using any HTTP library to your monitor's Ping API endpoints.
In this example, you are invoking logrotate directly and use cronitor ping to relay data to Cronitor:
/usr/sbin/logrotate && cronitor ping d3x0c1 --complete

Less reliably, use curl to send the same ping:
/usr/sbin/logrotate && curl -m 10 https://cronitor.link/d3x0c1/complete

Integration examples

How integration works

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.

Cronitor works anywhere that can make an outbound connection. Ping from a cron job or worker using CronitorCLI or curl, integrate directly with your app using any modern programming language, or monitor systems and services that can make http requests. There are examples here you can paste and use directly.

Learn More

Integration Guide Using CronitorCLI Ping API Guide

Use CronitorCLI to invoke your command:

# m h dom mon dow   command
0 1 * * * cronitor exec d3x0c1 /path/to/mysqlbackup.sh
    

Or use curl if you cannot install 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 curl if you cannot install 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

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

Integration without an API client

This section outlines the telemetry endpoints available to you when integrating with Cronitor using curl, PowerShell or a native HTTP client directly in your application code.

Covered in detail in our Ping API Guide, each monitor you create is assigned a unique ping api. Each ping api exposes endpoints you will use to tell Cronitor the status of your task: /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 ping is used to report that the job has started but has not necessarily completed yet.

/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 ping is used to report that the job has run successfully.

/fail

Ping the /fail endpoint to report a fatal error or failure of your task. Use the msg param to capture error messages. The most common place to send a /fail ping is within an exception handler or after your job returns a non-zero exit code.

/pause

The pause endpoint can be used to temporarily pause failure alerts on your monitor. When pausing, specify the number of hours to pause. Recovery notifications will still be sent if a failing monitor recovers while alerting is paused. All Cronitor alert emails include simple 1-click pause links.

Pro-tips & Points of Interest

  • If you have enabled Ping API authentication on your account settings page, all telemetry ping requests will require your Ping API key as a parameter. If you're using CronitorCLI, save your Ping API key to your configuration file using cronitor configure --ping-api-key <KEY> or set the CRONITOR_PING_API_KEY environment variable. If you're sending pings using Curl or a native HTTP client, provide the key via an &auth_key parameter.
  • 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
  • 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 redirect any unencrypted traffic.
  • 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 more important to you than clarity, you can abbreviate endpoints to their first initial: /r, /c and /f