Guides

Heartbeat Monitoring

Cronitor integration can be done in just a few minutes by anybody comfortable with a command prompt and HTTP Requests.

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 Telemetry Events 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

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 Telemetry Events 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 key.

    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 Telemetry Events 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

# Install CronitorCLI
curl -sOL https://cronitor.io/dl/cronitor-stable-linux-amd64.tgz
sudo tar xvf cronitor-stable-linux-amd64.tgz -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.

pip install cronitor
import cronitor
cronitor.api_key = '<API-KEY>'

# monitor any function
@cronitor.job('nightly-job')
def nightly_background_job(args):
    ...
# Or embed telemetry events in your application
monitor = cronitor.Monitor('nightly-job')
# send a run event (a job/process has started)
monitor.ping(state='run')
# send a complete event (a job/process has completed successfully)
monitor.ping(state='complete')
# send a failure event
monitor.ping(state='fail')
View on Github
npm install --save cronitor
// monitor any node cron job
const cron = require('cronitor')('<API-KEY>');
cron.wraps(require('node-cron')); // also works with require('cron');

cron.schedule('SendWelcomeEmail', '*/5 * * * *', function() {
    console.log('Sending welcome email to new sign ups every five minutes.');
});

// Or embed telemetry events in your application
const cronitor = require('cronitor')('<API-KEY>')
const monitor = new cronitor.Monitor('nightly-background-job');
// send a run event (a job/process has started)
monitor.ping({state: 'run'});
// send a complete event (a job/process has completed successfully)
monitor.ping({state: 'complete'});
// send a failure event
monitor.ping({state: 'fail'});
View on Github
gem install cronitor
require 'cronitor'
Cronitor.api_key = '<API-KEY>'

# monitor any function/code block
Cronitor.job 'nightly-job' do
  nightly_background_job()
end

# Or, embed telemetry events in your application
monitor = Cronitor.Monitor.new('nightly-job')
# send a run event (a job/process has started)
monitor.ping(state: 'run')
# send a complete event (a job/process has completed successfully)
monitor.ping(state: 'complete')
# send a failure event
monitor.ping(state: 'fail')
View on Github
// Maven
<dependency>
    <groupId>io.cronitor</groupId>
    <artifactId>client</artifactId>
    <version>1.4.0</version>
</dependency>

// Gradle
compile "io.cronitor:client:1.4.0
// Embed telemetry events in your application
CronitorClient cronitorClient = new CronitorClient('<API-KEY>');

// send a run event (a job/process has started)
cronitorClient.run('nightly-job');
// send a complete event (a job/process has completed successfully)
cronitorClient.complete('nightly-job');
// send a failure event
cronitorClient.fail('nightly-job');
View on Github
composer require cronitor/cronitor-php
$cronitor = new Cronitor\Client('<API-KEY>');

# monitor any function/code block
$cronitor->job('nightly-job', function() {
  $nightlyBackgroundJob();
});

# Or, embed telemetry events in your application
$monitor = $cronitor->monitor('nightly-job')
# send a run event (a job/process has started)
$monitor->ping(['state' => 'run'])
# send a complete event (a job/process has completed successfully)
$monitor->ping(['state' => 'complete'])
# send a failure event
$monitor->ping(['state' => 'fail'])

View on Github
# send an event
curl https://cronitor.link/p/<API-KEY>/nightly-job
# send a run event (a job/process has started)
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=run
# send a complete event (a job/process has completed successfully)
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=complete
# send a failure event
curl https://cronitor.link/p/<API-KEY>/nightly-job?state=fail

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 Telemetry Events API Guide, each monitor you create has a unique telemetry key. Send events via http requests 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 Telemetry Events API authentication on your account settings page, all telemetry ping requests will require your Telemetry Events API key as a parameter. If you're using CronitorCLI, save your Telemetry Events 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