Shell Scripts

You can easily add healthchecks monitoring to a shell script. All you have to do is make an HTTP request at an appropriate place in the script. curl and wget are two common command-line HTTP clients you can use.

# Sends an HTTP GET request with curl:
curl -m 10 --retry 5 https://healthchecks.sre.cfainstitute.org/ping/your-uuid-here

# Silent version (no stdout/stderr output unless curl hits an error):
curl -fsS -m 10 --retry 5 -o /dev/null https://healthchecks.sre.cfainstitute.org/ping/your-uuid-here

Here's what each curl parameter does:

-m <seconds>

Maximum time in seconds that you allow the whole operation to take.

--retry <num>

If an HTTP request fails, retry up to this many times. By default, curl uses an increasing delay between each retry (1s, 2s, 4s, 8s, ...). See also --retry-delay.

-f, --fail

Makes curl treat non-200 responses as errors.

-s, --silent

Silent or quiet mode. Hides the progress meter, but also hides error messages.

-S, --show-error

Re-enables error messages when -s is used.

-o /dev/null

Redirect curl's stdout to /dev/null (error messages still go to stderr).

Signaling Failure from Shell Scripts

You can append /fail or /{exit-status} to any ping URL and use the resulting URL to actively signal a failure. The exit status should be a 0-255 integer. healthchecks will interpret exit status 0 as success and all non-zero values as failures.

The following example runs /usr/bin/certbot renew, and uses the $? variable to look up its exit status:

#!/bin/sh

# Payload here:
/usr/bin/certbot renew
# Ping healthchecks
curl -m 10 --retry 5 https://healthchecks.sre.cfainstitute.org/ping/your-uuid-here/$?

Logging Command Output

When pinging with HTTP POST, you can put extra diagnostic information in the request body. If the request body looks like a valid UTF-8 string, healthchecks will accept and store the first 10 kB of the request body.

In the below example, certbot's output is captured and submitted via HTTP POST:

#!/bin/sh

m=$(/usr/bin/certbot renew 2>&1)
curl -fsS -m 10 --retry 5 --data-raw "$m" https://healthchecks.sre.cfainstitute.org/ping/your-uuid-here

Auto Provisioning New Checks

This example uses healthchecks auto provisioning feature to create a check "on the fly" if it does not already exist. Using this technique, you can write services that automatically register with healthchecks the first time they run.

#!/bin/bash

PING_KEY=fixme-your-ping-key-here

# Use system's hostname as check's slug
SLUG=$(hostname)

# Construct a ping URL and append "?create=1" at the end:
URL=https://healthchecks.sre.cfainstitute.org/ping/$PING_KEY/$SLUG?create=1

# Send a ping:
curl -m 10 --retry 5 $URL