• Sales: 1-800-961-2888
  • Support: 1-800-961-4454

Getting Started With Rackspace Monitoring CLI


Cloud Monitoring is an API driven cloud service built for infrastructure monitoring. It offers a simple yet powerful feature-set, allowing extreme flexibility in configuration and execution.

This guide is intended to be a supplement to the official technical documentation, not a replacement for it. 

Getting started with an API based monitoring system can be daunting when trying to rapidly scale infrastructure. To get your feet wet with the API, we have created Raxmon, a Command Line Interface (CLI) tool.


Step One: Setup 

Install RaxmonCLI

To avoid repeating the raxmon installation on each new Cloud Server, install it on your workstation and not your server.

Note: raxmon requires Python 2.5, 2.6 or 2.7.

The Rackspace-Monitoring CLI tool is available here as open source: https://github.com/racker/rackspace-monitoring-cli

The utility can be installed via PIP:

sudo pip install rackspace-monitoring-cli

Getting your API Key

You will need to get your API key in order to be able to administer Cloud Monitoring.

Now create a file named ~/.raxrc in your home folder, and fill it like so: 

[credentials]
username=my_user
api_key=myapikey66c90d41bdc151232f31f9f

An additional section is required in order to make use of the UK authentication endpoint (the default URL points to the US endpoint): 

[auth_api]
url=https://lon.identity.api.rackspacecloud.com/v2.0

Now run raxmon to see that you can connect properly.

$ raxmon-entities-list

Congratulations! It works!


Step Two: Getting Familar

Raxmon CLI has a variety of commands and abilities at its disposal. We're going to walk through generating one of the most used checks, an HTTP check.

HTTP checks will continually GET your webpage and make sure that it responds and doesn't timeout or get connection refused and alert if it returns something like a 404.

Raxmon mostly follows CRUD methodology, Create, Read (list), Update, Delete with five types:

See $ raxmon --help to see all of the commands available to raxmon.

We will need to update multiple items in one go, so let's review how to input lists and dictionaries in the terminal:

List
Use a comma delimited string. For example:
raxmon-checks-create --monitoring-zones=mzA,mzB,mzC

Dictionary
Use a comma delimited string of key=value pairs. For example
raxmon-entities-create --metadata="location=server room,tag=foobar"


Step Three: Monitoring an HTTP Page 

Create an Entity

Entities are Cloud Monitoring's name for server-like objects. Anything that has an IP address is defined as an entity. Currently Cloud Monitoring has no concept of our environment, so lets create an entity.

$ raxmon-entities-create --label my_first_server --ip-addresses="alias=10.10.10.10"
Resource created. ID: entZ4JPIfA

The option --ip-addresses="alias=10.10.10.10" specifies the IP address and an alias for the target. You can have multiple targets per node.

Now we need to create a check . To create a check we'll need a few things.

  • Check Type - In this case, remote.HTTP
  • A Label
  • Entity ID - In this case 'entZ4JPIfA'
  • Monitoring Zone - The data center we're going to monitor from
  • Target Alias - A key in the entity's 'ip_addresses' hash used to resolve this check to an IP address.
  • Any check specific details.

We have all of these, except the monitoring zone. Lets grab that now.

$ raxmon-monitoring-zones-list
<MonitoringZone: id=mzdfw label=dfw provider=Rackspace Monitoring ...>
<MonitoringZone: id=mzhkg label=hkg provider=Rackspace Monitoring ...>
<MonitoringZone: id=mzlon label=lon provider=Rackspace Monitoring ...>
<MonitoringZone: id=mzord label=ord provider=Rackspace Monitoring ...>
Total: 4

Now lets create that check. We'll use the entity id above, and the name of the target-alias we created before.

$ raxmon-checks-create --type remote.http --label http --entity-id entZ4JPIfA --monitoring-zones mzord --details="url=www.example.com,method=GET" --target-alias eth0
Resource created. ID: chNbqDaZrJ

Notification Addresses and Alarms

Checks are great, but we also need to be able to receive notifications. Lets create an e-mail address notification type now.

$ raxmon-notifications-create --label example-email --type email --details="address=user@email.com"
Resource created. ID: ntYgMnnipC

We also need to create a notification plan. This allows us to emit different types of alerts on different states. 

$ raxmon-notification-plans-create --label notification_plan_1 --critical-state ntYgMnnipC --warning-state ntYgMnnipC --ok-state ntYgMnnipC
Resource created. ID: npzwIZKV6o

Notifications are ONLY emitted when state changes. When a plan moves from OK state to Critical state, it will notify the "Critical State Notification." When it then changes from Critical to OK the "OK State Notification" will be used.

Now that we have a notification address and plan, we also need to create the alarm itself. Rackspace Cloud Monitoring uses alarms to evaluate the metrics of a check and decide if a notification plan should be executed.

$ raxmon-alarms-create --check-id=chNbqDaZrJ --criteria "if (metric[\"code\"] regex \"^[23]..$\") { return OK } return WARNING" --notification-plan npzwIZKV6o --entity-id entZ4JPIfA

Great! That's it. You now have a check, notification, and alarm. Lets look at the details:

raxmon-alarms-list --entity entZ4JPIfA --details
{'criteria': u'if (metric["code"] regex "^[23]..$") { return OK } return WARNING', 'driver': <rackspace_monitoring.drivers.rackspace.RackspaceMonitoringDriver object at 0x101d66710>, 'entity_id': u'entZ4JPIfA', 'id': u'albuOSvLjf', 'notification_plan_id': u'npzwIZKV6o','type': u'remote.http'}

Now anything but a 2XX or 3XX will return an error and you will be notified via e-mail. 

Conclusion

With these simple principles, you'll be able to create a robust and scalable monitoring system that gives you better insight into your infrastructure.  For more information, be sure to consult the Development Guide for Cloud Monitoring as well as the Cloud Monitoring FAQ.







© 2011-2013 Rackspace US, Inc.

Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License


See license specifics and DISCLAIMER