Monitoring

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

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

Integration examples

# m h dom mon dow   command

0 1 * * * cronitor exec d3x0c1 /path/to/mysqlbackup.sh

# m h dom mon dow   command

0 1 * * * CRONITOR_ID=d3x0c1 cronitor /path/to/mysqlbackup.sh

# 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

#!/usr/bin/env bash
cronitor ping d3x0c1 --run
/path/to/do_things.sh
cronitor ping d3x0c1 --complete

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

import requests
requests.get(
   'https://cronitor.link/d3x0c1/run',
   timeout=10
)

# Application Code Here

requests.get(
   'https://cronitor.link/d3x0c1/complete',
   timeout=10
)

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

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

require 'open-uri'
open(
   'https://cronitor.link/d3x0c1/run',
   :read_timeout=>10
)

# Application Code Here

open(
   'https://cronitor.link/d3x0c1/complete',
   :read_timeout=>10
)

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

file_get_contents('https://cronitor.link/d3x0c1/run');
# Application Code Here
file_get_contents('https://cronitor.link/d3x0c1/complete');

$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);

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