Guides

Heartbeat Monitoring

• crontab

• python

• node

• php

• ruby

• java

• http

# 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

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')

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'});

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')

// 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');

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'])

# 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