About cloudviz

This package exposes Amazon CloudWatch as a data source for Google Chart Tools. With it, you can quickly generate graphs like this:

Cloudviz is proudly sponsored by Bizo. For details on the cloudviz's origin, see this blog post.

If you're looking for easiest way to start graphing CloudWatch data, check out Cloudgrapher. Cloudgrapher is a free CloudWatch dashboard, and is effectively a hosted, batteries-included extension of cloudviz.

Getting started

1. Familiarize yourself with:
   • Amazon CloudWatch (docs)
   • Google Visualization API (docs)
2. Download and install:
   • boto - a Python interface for Amazon Web Services
   • gviz_api - a Python library for creating Google Visualization API data sources
3. Set **AWS_ACCESS_KEY_ID **and **AWS_SECRET_ACCESS_KEY **in settings.py
4. Make cloudviz.py web-accessible using your favorite HTTP server

Using cloudviz

cloudviz expects the following query parameters as a JSON-encoded string passed to a qs parameter. Default values for each parameter may be set in settings.py:

• __namespace __(str) - CloudWatch namespace (e.g., "AWS/ELB")
• __metric __(str) - CloudWatch metric (e.g., "Latency")
• __unit __(str) - CloudWatch unit (e.g., "Seconds")
• __statistics __(list of str) - CloudWatch statistics (e.g., ["Average","Maximum"])
• __dimensions __(dict of str) - CloudWatch dimensions (e.g., {"LoadBalancerName": "example-lb"})
• __end_time __(date) - end time for queried interval (e.g., new Date)
• __start_time __(date) - start time for queried interval (e.g., start_time.setDate(end_time.getDate-3))
• __range __(int) - desired time range, in hours, for queried interval (e.g., 24). Note: range may be substituted for start_time, end_time, or both:
  • if range and end_time are specified, start_time is calculated as ( end_time - range )
  • if range and start_time are specified, end_time is calculated as ( start_time + range )
  • if only range is specified, end_time is set to the current time and start_time is calculated as ( current time - range )
• __period __(int) - (optional) CloudWatch period (e.g., 120). Notes: must be a multiple of 60; if period is not specified, it will be automatically calculated as the smallest valid value (resulting in the most data points being returned) for the queried interval.
• __region __(str) - (optional) AWS region (e.g., "us-west-1"; default is "us-east-1")
• __calc_rate __(bool) - (optional) when set to True and statistics includes "Sum", cloudviz converts Sum values to per-second Rate values by dividing Sum by seconds in period (e.g., for RequestCount, 150 Requests per period / 60 seconds per period = 2.5 Requests per second)
• __cloudwatch_queries __(list of dict) - encapsulates each CloudWatch query, allowing for multiple queries to be graphed in a single chart. Minimally, **cloudwatch_queries **must contain one dict with prefix defined. Optionally, any of the above parameters may also be defined inside one or more **cloudwatch_queries **
  • __prefix __(str) - text identifier for data returned by a single CloudWatch query. This is prepended to the chart label of each data series (e.g., "My LB ")

Example: Graphing CPU utilization of two instances

Here's a JavaScript snippet for building a URL to pass to cloudviz. See examples/host-cpu.html for the rest of the code. Note that **start_time **and **end_time **are set in settings.py.

var qa = {  
            "namespace": "AWS/EC2",       // CloudWatch namespace (string
            "metric": "CPUUtilization",   // CloudWatch metric (string)
            "unit": "Percent",            // CloudWatch unit (string)
            "statistics": ["Average","Maximum"],      // CloudWatch statistics (list of strings)
            "period": 600,                // CloudWatch period (int)
            "cloudwatch_queries":         // (list of dictionaries)
            [   
                {
                    "prefix": "Instance 1 CPU ",   // label prefix for associated data sets (string)
                    "dimensions": { "InstanceId": "i-bd14d3d5"} // CloudWatch dimensions (dictionary)
                },
                {
                    "prefix": "Instance 2 CPU "
                    "dimensions": { "InstanceId": "i-c514d3ad"}
                }
            ]
         };

var qs = JSON.stringify(qa);
var url = 'http://' + window.location.host + '/cloudviz?qs=' + qs;  // assumes cloudviz.py is called at /data

The resulting URL should look something like this: http://localhost:8080/cloudviz?qs={%22namespace%22:%22AWS/EC2%22,%22metric%22:%22CPUUtilization%22,%22unit%22:%22Percent%22,%22statistics%22:[%22Average%22,%22Maximum%22],%22period%22:600,%22cloudwatch_queries%22:[{%22prefix%22:%22Instance%201%20CPU%20%22,%22dimensions%22:{%22InstanceId%22:%22i-bd14d3d5%22}},{%22prefix%22:%22Instance%202%20CPU%20%22,%22dimensions%22:{%22InstanceId%22:%22i-c514d3ad%22}}]}&tqx=reqId%3A0

And the graph, when passed through Google's Visualization API:

More examples

Additional examples can be found in examples/, and are written to act as plug-and-play templates.

Licensing

Copyright 2010 Bizo, Inc. (Mike Babineau <mike@bizo.com>)

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.