A node.js agent which creates and removes CloudWatch alarms and submits CloudWatch metrics.

Install & Configure

npm install cloudwatch-agent

• Edit settings and add your AWS IAM user's key and secret

Configure to submit metrics

• Choose which "checks" to enable and add them to the "activeChecks" array in settings.example.json

Configure to create/remove alarms

• See alarms/sample-alarms.json and edit to add alarms.

In general

• Refer to the CloudWatch API documentation for all available options when creating alarms or submitting metrics.

Usage

Create alarms

cloudwatch-agent --config=/usr/local/etc/cloudwatch-agent/settings.json \
    --op create \
    --def /usr/local/etc/cloudwatch-agent/alarms

Delete alarms

cloudwatch-agent --config=/usr/local/etc/cloudwatch-agent/settings.json \
    --op remove \
    --def /usr/local/etc/cloudwatch-agent/alarms

Run as agent to submit metrics

cloudwatch-agent --config=/usr/local/etc/cloudwatch-agent/settings.json \
    --op daemonize \
    --def.local /usr/local/etc/cloudwatch-agent/checks
    --def.core /usr/lib/node_modules/cloudwatch-agent/checks

Run from local machine as developer convenience

cloudwatch-agent --config=/usr/local/etc/cloudwatch-agent/settings.json \
    --op daemonize \
    --def.local /usr/local/etc/cloudwatch-agent/checks
    --def.core /usr/lib/node_modules/cloudwatch-agent/checks
    --region us-east-1
    --instanceId <some-instance-id>
    --instanceName <some instance name>

If you do not provide the --region or --instanceId arguments, cloudwatch agent will attempt to query the EC2 instance metadata API which will not be available from any machine which is not an EC2.

Write your own checks

There are not many limitations in how you write your own checks. Refer to the example checks in ./checks

Note, you can write a check that itself submits multiple datapoints for multiple different metrics. This is useful for cases where you have related metrics, such as a check that submits the total number of TCP connections, and you would also like to submit the number of TCP connections where the peer port is :5984. To do this, make metricname, unit both arrays, and pass an array value when the check callback is called. For example:

var exec = require('child_process').exec;
exports.definition = {
    "metricname": ["ConnectionsTotal", "ConnectionsCouchDB"],
    "namespace": "System/Linux",
    "unit": "Count", // Make array if ConnectionsTotal unit differs from ConnectionsCouchDB
    "interval": 60000,
    "command": function(options, cb) {
        // Your code to determine whatever
        cb(null, [val1, val2]); // Values must be in same order as metricname
    }
}