Turn Monitoring Off During Maintenance, Automagically

How long does your maintenance window last? I know you block it out on the Alertra website for 2 hours every Sunday, but does it really take that long? Sunday night the network guy and a veterinarian check over the hamsters powering the servers. Some weeks the hamsters are all 100% and ready to go another 7 days and some weeks they are lazy and unmotivated and need to shown the bit from The Lion King where Scar plays with his food. So your maintenance could take a couple of minutes or might really take that 2 hours, but the time is blocked out on the Alertra site and your site isn't getting checked until the maintenance window closes. Or is it.... If your nightly or weekly maintenance is automated, say by having monitors hooked up to the hamsters and automatically starting the "motivational" video when they are slacking, then you could plug into the Alertra API and start and stop your site maintenance programmatically. The Alertra API is simple. Really simple. It is implemented as a REST service which uses HTTP URLs, command types and data exchange mechanisms. So you can access the Alertra API and you don't even have to be the l33t Russian hacker from Goldeneye to do it.

He must be compiling his code.

In fact I was kind of giggling when I wrote the code for this article. Your experience may vary though.

Concept

To access your device's maintenance schedule via the Alertra API we will perform the following steps:

1. Request an API key from support.
2. Get a list of devices.
3. Use the device ID to act on that device.

You only need to get an API key once. Send us an email from your primary Alertra account and we'll send you a key. Since the website doesn't force device names to be unique within your account, you need the device list to determine what the unique device identifier is for the one you want to act upon.

Bash

Source Code In this example I'll show you how to start and stop your device's maintenance from inside a bash shell script. The source file contains the commands to start maintenance, stop maintenance, and get a list of devices, but lets look at the guts of it. The shell script is just a wrapper around the curl program. You probably already have curl installed if you are using a platform based on Linux. The curl command to access the Alertra API and get a list of devices looks like this:

curl -H "Alertra-API-Key: $APIKEY" https://api.alertra.com/v1.1/devices

where $APIKEY is the API key we sent you. You might want to pipe that output to a file so you can look through it. The response is a text file in the [json][http://json.org/] format. It can be difficult to read json, and at least within the Unix command line there aren't good ways to handle it that don't involve installing third-party packages. If you'd like a viewer for the data there are several on the web. I like [this one][http://www.jsoneditoronline.org/] because I have a zillion devices and the viewer has a search function. Once you have the API key and the device key, starting maintenance on a device looks like this:

curl -X PUT -d "Duration=02:00" -H "Alertra-API-Key: $APIKEY" https://api.alertra.com/v1.1/devices/$DEVICEKEY/start-maintenance

Here we do a PUT instead of a GET. The -d option passes some data to the call, in this case the duration of the maintenance window. Here I've set it to 2 hours, but you can use any value from 01:00 to 72:00. You do have to specify a value. If you want to put a device in indefinite maintenance you'll need to do that manually from the website. This is so if something goes wrong with your maintenance program and the call to stop the maintenance isn't made, then the device will still eventually come out of maintenance and hopefully alert you. We don't have to wait for the maintenance window to expire though! Once the hamsters have spent enough time pondering what it would be like to feel the esophageal muscles of a cranky lion push them toward certain doom it is time to stop the maintenance window. Another curl PUT command does the trick:

curl -X PUT -H "Alertra-API-Key: $APIKEY" -H "Content-Length: 0" https://api.alertra.com/v1.1/devices/$DEVICEKEY/stop-maintenance

The Alertra webserver throws an error message if you send a PUT without a "Content-Length" header and curl doesn't send one at all if you don't send any data. So the -H command forces the "Content-Length" header and sets it to 0. That's it! The workflow is:

curl [gobbledygook to start maintenance window]
threaten hamsters
curl [gobbledygook to stop maintenance window]

Easy peasy.

Source Code

Listing 1. Bash Shell Script

#!/bin/sh

APIKEY="YOUR ACCOUNT API KEY"

case $1 in
    devices)
        curl -H "Alertra-API-Key: $APIKEY" https://api.alertra.com/v1.1/devices
    ;;
    start)
        curl -X PUT -d "Duration=$3" -H "Alertra-API-Key: $APIKEY" https://api.alertra.com/v1.1/devices/$2/start-maintenance
    ;;
    stop)
        curl -X PUT -H "Alertra-API-Key: $APIKEY" -H "Content-Length: 0" https://api.alertra.com/v1.1/devices/$2/stop-maintenance
    ;;    
esac