cloudwatch-to-graphite 0.8.1

Helper for pushing AWS CloudWatch metrics to Graphite

Cloudwatch-to-Graphite (leadbutt) is a small utility to take metrics from CloudWatch to Graphite.

Installation

Install using pip:

pip install cloudwatch-to-graphite

Configuring boto

Cloudwatch-to-Graphite uses boto, so make sure to follow its configuration instructions. The easiest way to do this is to set up the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

Usage

Configuration Files

If you have a simple setup, the easiest way to get started is to set up a config.yaml. You can copy the included config.yaml.example. Then just run:

leadbutt

If you have several configs you want to switch between, you can specify a custom configuration file:

leadbutt --config-file=production.yaml -n 20

You can even generate configs on the fly and send them in via stdin by setting the config file to ‘-‘:

generate_config_from_inventory | leadbutt --config-file=-

There’s a helper to generate configuration files called plumbum. For now, you’ll have to read the source of plumbum.py for usage.

Sending Data to Graphite

If your graphite server is at graphite.local, you can send metrics by chaining with netcat:

leadbutt | nc -q0 graphite.local 2003

Or if you want to use UDP:

leadbutt | nc -uw0 graphite.local 2003

If you need to namespace your metrics for a hosted Graphite provider, you could provide a custom formatter, but the easiest way is to just run the output through awk:

leadbutt | \
  awk -v namespace="$HOSTEDGRAPHITE_APIKEY" '{print namespace"."$0}' | \
  nc -uw0 my-graphite-provider.xxx 2003

Customizing Your Graphite Metric Names

Set the Formatter option to set the template used to generate Graphite metric names. I wasn’t sure what should be default, so I copied cloudwatch2graphite’s. Here’s what it looks like:

cloudwatch.%(Namespace)s.%(dimension)s.%(MetricName)s.%(statistic)s.%(Unit)s

TitleCased variables come directly from the YAML configuration, while lowercase variables are derived:

• statistic – the current statistic since Statistics can be a list

• dimension – the dimension value, e.g. “i-r0b0t” or “my-load-balancer”

The format string is Python’s %-style.

config.yaml

What metrics are pulled is in a YAML configuration file. See the example config.yaml.example for an idea of what you can do.

Developing

Install requirements:

pip install -r requirements.txt

Running test suite:

make test

Verifying tests run over all supported Python versions:

tox

Useful References

• CloudWatch Reference

• boto CloudWatch docs

Prior Art

Cloudwatch-to-Graphite was inspired by edasque’s cloudwatch2graphite. I was looking to expand it, but I wanted to use boto.