Shell Scripts

You can easily add Tom Knows Tech Health Checks 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.tomknows.tech/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.tomknows.tech/ping/your-uuid-here

Here's what each curl parameter does:

-m <seconds>

Maximum time in seconds that you allow the HTTP request to take. If you use the --retry parameter, then the time counter is reset at the start of each retry.

--retry <num>

On transient errors, retry up to this many times. By default, curl uses an increasing delay between each retry (1s, 2s, 4s, 8s, ...). See also --retry-delay. Transient errors are: timeouts, HTTP status codes 408, 429, 500, 502, 503, 504.

-f, --fail

Makes curl treat non-200 responses as errors, and return error 22.

-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

Redirects 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. Tom Knows Tech Health Checks 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 Tom Knows Tech Health Checks
curl -m 10 --retry 5 https://healthchecks.tomknows.tech/ping/your-uuid-here/$?

Note on pipelines (command1 | command2 | command3) in Bash scripts: by default, a pipeline's exit status is the exit status of the rightmost command in the pipeline. Use set -o pipefail if you need the pipeline to return non-zero exit status if any part of the pipeline fails:

#!/bin/sh

set -o pipefail
pg_dump somedb | gpg --encrypt --recipient [email protected] --output somedb.sql.gpg
# Without pipefail, if pg_dump command fails, but gpg succeeds, $? will be 0,
# and the script will report success.
# With pipefail, if pg_dump fails, the script will report the exit code returned by pg_dump.
curl -m 10 --retry 5 https://healthchecks.tomknows.tech/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, Tom Knows Tech Health Checks 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.tomknows.tech/ping/your-uuid-here

Auto Provisioning New Checks

This example uses Tom Knows Tech Health Checks 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 Tom Knows Tech Health Checks 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.tomknows.tech/ping/$PING_KEY/$SLUG?create=1

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