2.7 KiB
Shell Scripts
You can easily add SITE_NAME 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 PING_URL
# Silent version (no stdout/stderr output unless curl hits an error):
curl -fsS -m 10 --retry 5 -o /dev/null PING_URL
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.
SITE_NAME 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 SITE_NAME
curl -m 10 --retry 5 PING_URL/$?
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, SITE_NAME will accept and store the first PING_BODY_LIMIT_FORMATTED 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" PING_URL
Auto Provisioning New Checks
This example uses SITE_NAME 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 SITE_NAME 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=PING_ENDPOINT$PING_KEY/$SLUG?create=1
# Send a ping:
curl -m 10 --retry 5 $URL