Keeping CloudWatch Dashboards up to date using AWS Lambda

[
    {
        "dashboardName": " MyAutoScalingDashboard ",
        "ec2DescribeInstanceParams": {
            "Filters": [
                {
                    "Name": "instance-state-name",
                    "Values": [ "running" ]
                },
                {
                    "Name": "tag:aws:autoscaling:groupName",
                    "Values": [ "MyAutoScalingGroup" ]
                }
            ]
        }
    }
]

//
// EC2 Dashboard Updater
// This script will keep EC2 graphs on a chosen list of CloudWatch Dashboards up to date. In the CloudWatch Events
// console create a rule to call this Lambda whenever and EC2 instance changes state.
//
// Configure this script with the AWS_DASHBOARDS environment variable. The content of AWS_DASHBOARDS indicates
// which dashboards to update with which EC2 instances.  The value is an array in JSON format. Each array element
// is an object with two properties, dashboardName and ec2DescribeInstanceParams. dashboardName is the dashboard to
// update and ec2DescribeInstanceParams are parameters to pass to EC2 DescribeInstances API, to determine which
// instances to update the graphs with.
//
// For example, set AWS_DASHBOARDS to the following to keep 'MyDashboard' up to date with the instances in the
// AutoScalingGroup 'MyAutoScalingGroup':
//
// [
//     {
//         dashboardName: 'MyDashboard',
//         ec2DescribeInstanceParams: {
//             Filters: [
//                 {
//                     Name: 'tag:aws:autoscaling:groupName',
//                     Values: [ 'MyAutoScalingGroup' ]
//                 }
//             ]
//         }
//     }
// ]
//
// Limitations:
// - it will only update graphs whose first metric is an EC2 instance metric, all other metrics on the graph
//   will be replaced with these metrics
// - metrics can not have custom periods or statistics, the graph defaults will be used
//

'use strict'
var _ = require('lodash'),
    co = require('co'),
    AWS = require('aws-sdk'),

    EC2_NAMESPACE = 'AWS/EC2',
    INSTANCE_ID_DIM = 'InstanceId',
    REPEAT_PREVIOUS = '...',
    NAME_TAG = 'Name',
    METRIC_WIDGET_TYPE = 'metric';

function getDashboards() {
    let dashboardDef = process.env.AWS_DASHBOARDS,
        dashboards;

    if (! dashboardDef) {
        throw 'Environment variable AWS_DASHBOARDS is not set. It should be set with JSON array, e.g [{"dashboardName": "myDashboard"}]';
    }

    try {
        dashboards = JSON.parse(dashboardDef);
    } catch (err) {
        throw 'Error, AWS_DASHBOARDS is not valid JSON';
    }

    if (! Array.isArray(dashboards)) {
        throw 'Expecting AWS_DASHBOARDS to be an array';
    }
    return dashboards;
}

function ec2MetricsFromDescribeInstances(ec2DescribeInstances, metricName) {
    return _.chain(ec2DescribeInstances.Reservations).
        map('Instances').
        flatten().
        map(function(instance) {
                let idAndLabel = {
                    id: instance.InstanceId,
                    label: instance.InstanceId
                };
                _.each(instance.Tags, (tag) => {        // Use Name tag instead of InstanceId as label, if it exists
                    if (tag.Key === NAME_TAG) {
                        idAndLabel.label = tag.Value;
                        return false;
                    }
                });
                return idAndLabel;
            }).
        sortBy(['label']).
        map((idAndLabel, i) => {


                var metric = i == 0 ?
                [ EC2_NAMESPACE, metricName, INSTANCE_ID_DIM, idAndLabel.id ] :
                [ REPEAT_PREVIOUS, idAndLabel.id ];

                if (idAndLabel.id != idAndLabel.label) {
                    metric.push({label: idAndLabel.label});
                }
                return metric;
            }).
        value();
}

function* getEC2Metrics(dashboardContext, region, metricName) {
    var params = dashboardContext.dashboard.ec2DescribeInstanceParams || {},
        ec2Cache = dashboardContext.ec2Cache,
        ec2DescribeInstances;

    // ec2Cache is a cache of instance responses per region for the current dashboard, to limit calls to EC2
    if (!ec2Cache) {
        dashboardContext.ec2Cache = {};
    } else if (ec2Cache[region]) {
        ec2DescribeInstances = ec2Cache[region];
    }

    if (!ec2DescribeInstances) {
        // Not in cache, call EC2 to get list of regions
        let ec2Client = new AWS.EC2({region: region});
        ec2DescribeInstances = yield ec2Client.describeInstances(params).promise(),
        dashboardContext.ec2Cache[region] = ec2DescribeInstances;
    }

    return ec2MetricsFromDescribeInstances(ec2DescribeInstances, metricName);
}

function* updateDashboard(cloudwatchClient, dashboardContext, dashboardBody) {
    var newDashboard = _.cloneDeep(dashboardBody),
        widgets = newDashboard.widgets,
        dashboardName = dashboardContext.dashboard.dashboardName;

    for (let i = 0; i < widgets.length; i++) {
        let widget = widgets[i],
            metrics = widget.properties.metrics,
            region = widget.region;

        // Check to see if it's a metric widget and first metric is an EC2 Instance metric
        if (widget.type === METRIC_WIDGET_TYPE && metrics && (metrics[0].length === 4 || metrics[0].length === 5) &&
            metrics[0][0] === EC2_NAMESPACE && metrics[0][2] === INSTANCE_ID_DIM) {
            let ec2Metrics = yield getEC2Metrics(dashboardContext, region, metrics[0][1]);
            widget.properties.metrics = ec2Metrics;
        }
    }

    if (JSON.stringify(dashboardBody) !== JSON.stringify(newDashboard)) {
        console.log(`Updating dashboard ${dashboardName} to:`, JSON.stringify(newDashboard));

        // Save updated dashboard
        yield cloudwatchClient.putDashboard({
            DashboardName: dashboardName,
            DashboardBody: JSON.stringify(newDashboard)
        }).promise();
    } else {
        console.log(`Dashboard ${dashboardName} is unchanged, update skipped`);
    }
}

exports.handler = (event, context, callback) => {
    var dashboards = getDashboards(),
        cloudwatchClient = new AWS.CloudWatch(),
        dashboard,
        dashboardContext;

    try {
        co(function* () {
            for (let i = 0; i < dashboards.length; i++) {
                dashboard = dashboards[i];
                dashboardContext = { dashboard: dashboard };
                if (dashboard.dashboardName) {
                    let dashboardResponse = yield cloudwatchClient.getDashboard({
                                                    DashboardName: dashboard.dashboardName }).promise(),
                        dashboardBody = JSON.parse(dashboardResponse.DashboardBody);

                    yield updateDashboard(cloudwatchClient, dashboardContext, dashboardBody);
                }
            }
            callback(null, 'Update complete');
        });
    } catch (err) {
        callback(err);
    }
};