cloudviz
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
- Familiarize yourself with:
-
Download and install:
- boto – a Python interface for Amazon Web Services
- gviz_api – a Python library for creating Google Visualization API data sources
- pytz – world timezone definitions
-
Set **AWS_ACCESS_KEY_ID **and **AWS_SECRET_ACCESS_KEY **in
settings.py
-
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 forstart_time
,end_time
, or both:-
if
range
andend_time
are specified,start_time
is calculated as (end_time
–range
) -
if
range
andstart_time
are specified,end_time
is calculated as (start_time
+range
) -
if only
range
is specified,end_time
is set to the current time andstart_time
is calculated as ( current time –range
)
-
if
-
period
(int) – (optional) CloudWatch period (e.g., 120). Notes: must be a multiple of 60; ifperiod
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 andstatistics
includes “Sum”, cloudviz converts Sum values to per-second Rate values by dividing Sum by seconds inperiod
(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 morecloudwatch_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
michael.babineau@gmail.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.