Rackspace API/Cloud Monitoring

NOTE: This article was written in 2014 and is no longer maintained.

This article will show various examples and techniques for working with Rackspace's Cloud Monitoring (MaaS) RESTful API.

HOWTO: send Cloud Monitoring SMS alerts to multiple phone numbers

In this article, I will show you how to create a Cloud Monitoring check and send the alerts ("alarms") as an SMS to multiple phone numbers. This must be done either via direct API calls or you can use the raxmon utility. In this article, I will use direct API calls via cURL.

Note: This article assumes you already have the Cloud Monitoring Agent installed on the Cloud Server for which you will be setting up Cloud Monitoring checks.

Step #0 — Setup your environment variables (and authenticate to receive your 24-hour valid token)

$ ACCOUNT=<RAX_ACCOUNT>
$ USERNAME=<RAX_USERNAME>
$ APIKEY=<RAX_API_KEY>
$ TOKEN=`curl -sXPOST https://identity.api.rackspacecloud.com/v2.0/tokens \
         -d'{"auth":{"RAX-KSKEY:apiKeyCredentials": "username":"'$USERNAME'","apiKey":"'$APIKEY'"}}}' \
         -H"Content-type:application/json" | \
         python -c 'import sys,json;data=json.loads(sys.stdin.read());print data["access"]["token"]["id"]'`

Step #1 — Get the entity ID for the Cloud Server in question

$ ENDPOINT=https://monitoring.api.rackspacecloud.com/${ACCOUNT}
$ curl -H "X-Auth-Token: $TOKEN" \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       "$ENDPOINT/entities"
$ ENTITY_ID=<FROM_OUTPUT_ABOVE>

Step #2 — Create notification destinations for Cloud Monitoring alerts/"alarms"

$ # Create notification for 1st phone number:
$ PHONE_N1="+12065550001"
$ curl -XPOST -H "X-Auth-Token: $TOKEN" \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -d "{\"details\": {\"phone_number\": \"$PHONE_N1\"},
            \"type\": \"sms\", \"label\": \"sms\"}' \
       "$ENDPOINT/notifications" | python -mjson.tool
$ NOTIFICATION_ID1=ntxxxxxxxx  # See the "X-Object-ID:" header response
 
$ # Create notification for 2nd phone number:
$ PHONE_N2="+12065550002"
$ curl -XPOST -H "X-Auth-Token: $TOKEN" \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -d "{\"details\": {\"phone_number\": \"$PHONE_N2\"},
            \"type\": \"sms\", \"label\": \"sms\"}' \
       "$ENDPOINT/notifications" | python -mjson.tool
$ NOTIFICATION_ID2=ntxxxxxxxx  # See the "X-Object-ID:" header response

Step #3 — Create a notification plan

Note: Here we will have Cloud Monitoring alert us for three different states: "WARNING", "CRITICAL", and when back to normal/"OK".

$ curl -iXPOST \
       -H "X-Auth-Token: $TOKEN" \
       -H "Content-Type: application/json" \
       -d "{\"label\": \"SMS Notification\",
            \"warning_state\": [\"$NOTIFICATION_ID1\", \"$NOTIFICATION_ID2\"],
            \"critical_state\": [\"$NOTIFICATION_ID1\", \"$NOTIFICATION_ID2\"],
            \"ok_state\": [\"$NOTIFICATION_ID1\", \"$NOTIFICATION_ID2\"]
          }" \
       "$ENDPOINT/notification_plans"
$ NOTIFICATION_PLAN_ID=npxxxxxxxx  # See the "X-Object-ID:" header response

Step #4 — Create a Cloud Monitoring check

Note: Here we will create a remote ping check (remote servers located in DFW, ORD, and LON) on the Cloud Server's public IPv4 address. Also note that '{ "count": 5 }' is the number of pings to send within a single check (this is optional and the maximum value allowed is 15). The Cloud Monitoring service will run the ping check every 60 seconds and timeout (i.e., fail) after 30 seconds.

$ curl -iXPOST \
       -H "X-Auth-Token: $TOKEN" \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -d '{ "details" : { "count": 5 },
             "label" : "ping-check",
             "monitoring_zones_poll" : [ "mzdfw", "mzord", "mzlon" ],
             "period" : 60,
             "target_alias" : "public0_v4",
             "timeout" : 30,
             "type" : "remote.ping"
           }' \
       "${ENDPOINT}/entities/${ENTITY_ID}/checks"
$ CHECK_ID=chxxxxxxxx  # See the "X-Object-ID:" header response

You can test this check with the following:

$ curl -sXPOST \
       -H "X-Auth-Token: $TOKEN" \
       -H "Accept: application/json" \
       "$ENDPOINT/entities/${ENTITY_ID}/checks/chw3sYBsFz/test"|\
       python -mjson.tool

Step #5 — Create the Cloud Monitoring alert/"alarm"

Note: In this example, I will have the Cloud Monitoring service alert me if the remote ping check returns a packet loss of greater than 5% ("WARNING") or greater than 20% ("CRITICAL").

$ curl -iXPOST \
       -H "X-Auth-Token: $TOKEN" \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -d "{\"label\": \"ping-check-sms\",
            \"notification_plan_id\": \"$NOTIFICATION_PLAN_ID\",
            \"check_id\": \"$CHECK_ID\",
            \"criteria\": \"if (metric['available'] < 80) {\n  return new AlarmStatus(CRITICAL, 'Packet loss is greater than 20%');\n}\n\nif (metric['available'] < 95) {\n  return new AlarmStatus(WARNING, 'Packet loss is greater than 5%');\n}\n\nreturn new AlarmStatus(OK, 'Packet loss is normal');\"}" \
       "$ENDPOINT/entities/$ENTITY_ID/alarms"

That's it! Now, every time your Cloud Server fails the remote ping test for the criteria given, the Cloud Monitoring service will send SMS alerts to those two phone numbers.

Links

Mobile alerts from Cloud Monitoring

See also

• Rackspace API