Statful-aws-collector NPM

Statful AWS Collector

Staful AWS Collector built in NodeJS. This is intended to collect metrics from AWS CloudWatch and send them to Statful.

Supported NodeJS Versions

Statful AWS Collector Version	Tested NodeJS versions
1.x.x	`4` and `Stable`

Installation

$ npm install -g statful-aws-collector

Quick start

After installing Statful AWS Collector you are ready to use it. The quickest way is to do the following:

$ statful-aws-collector generate-config /etc/statful-aws-collector/conf/

# Update some info in the statful-aws-collector-conf.json: accessKeyId, secretAccessKey and the statful api token

$ statful-aws-collector start /etc/statful-aws-collector/conf/statful-aws-collector-conf.json

Examples

You can find here some useful usage examples of the Statful AWS Collector. In the following examples are assumed you have already installed the collector globally and followed the Quick Start.

Collect a list of metrics

{
  "statfulAwsCollector": {
    ... ,
    "period": 60,
    "statistics": ["SampleCount", "Average", "Sum", "Minimum", "Maximum"],
    "metricsList": {
      "type": "white",
      "metricsPerRegion": {
        "us-west-2": [
          {
            "Namespace": "AWS/ELB"
          },
          {
            "Namespace": "AWS/AutoScaling",
            "MetricName": "GroupMinSize"
          },
          {
            "Namespace": "AWS/AutoScaling",
            "MetricName": "GroupMaxSize"
          },
          {
            "Namespace": "AWS/AutoScaling",
            "MetricName": "GroupStandbyInstances"
          }
        ]
      }
    },
    ...
  },
  ...
}

Collect a metric with different dimensions

{
  "statfulAwsCollector": {
    ... ,
    "period": 60,
    "statistics": ["SampleCount", "Average", "Sum", "Minimum", "Maximum"],
    "metricsList": {
      "type": "white",
      "metricsPerRegion": {
        "us-west-2": [
          {
            "Namespace": "AWS/ELB"
          },
          {
            "Namespace": "AWS/Billing",
            "MetricName": "EstimatedCharges",
            "Dimensions": [
            	{
            		"Name": "ServiceName",
            		"Value": "Service1"
            	},
            	{
            		"Name": "ServiceName",
            		"Value": "Service12"
            	},
            	{
            		"Name": "Currency",
            		"Value": "USD"
            	},
            	{
            		"Name": "Currency",
            		"Value": "EUR"
            	}
            ]
          }
        ]
      }
    },
    ...
  },
  ...
}

Collect metrics from more than one region

{
  "statfulAwsCollector": {
    ... ,
    "period": 300,
    "statistics": ["SampleCount", "Average", "Sum", "Minimum", "Maximum"],
    "metricsList": {
      "type": "white",
      "metricsPerRegion": {
      	"eu-central-1": [
          {
            "Namespace": "AWS/Billing"
          }
        ],
      	"us-west-1": [
          {
            "Namespace": "AWS/Billing"
          }
        ],
        "us-west-2": [
          {
            "Namespace": "AWS/Billing"
          }
        ]
      }
    },
    ...
  },
  ...
}

Reference

Detailed reference if you want to take full advantage from Statful AWS Collector.

CLI

$ statful-aws-collector generate-config <path>

Creates a default configuration at the given path. If the given path doesn't exists, it will be created.

$ statful-aws-collector start <path>

Starts the collector with the config on given path.

$ statful-aws-collector help

Shows a small help for the collector.

Configuration

In the configuration file you can find 3 main sections: statfulAwsCollector, bunyan, statfulClient.

StatfulAWSCollector

Option	Description	Type	Default	Required
credentials	Defines the credentials to access AWS.	`object`	none	YES
period	Defines the global output level. Valid Periods: `60, 120, 180, 300`	`number`	60	YES
statistics	Define the statistcs for which data should be collected. Valid Statistics: `SampleCount, Average, Sum, Minimum, Maximum`	`array`	`["SampleCount", "Average", "Sum", "Minimum", "Maximum"]`	YES
metricsList	Defines metrics to collect from AWS. Here you should only configure the `metricsPerRegion` which is an object organized by AWS region. Inside each region you should set a list of metrics object to collect. Each metric object supports a `Namespace`, `MetricName` and `Dimensions`. Please check the AWS documentation (AWS Metric Reference and Amazon CloudWatch Namespaces, Dimensions, and Metrics Reference) and the Examples section to get more information about the metrics object.	`object`	none	YES
signals	Defines the proccess signals for which collector should be stopped. Any valid NodeJS signal can be added.	`array`	`["SIGTERM", "SIGINT", "SIGABRT", "SIGUSR2"]`	YES

Bunyan

Option	Description	Type	Default	Required
name	Defines the logger name.	`string`	none	YES
level	Defines the global output level.	`string`	none	NO
streams	Define the logger streams. By default, when the value is an empty array, logger will output to `proccess.stdout`.	`array`	`[]`	YES

NOTE: We had only documented some bunyan config fields here but you can set all the supported configs by Bunyan.

To get more information please read the Bunyan documentation.

StatfulClient

Option	Description	Type	Default	Required
app	Defines the application global name. If specified sets a global tag `app=setValue`.	`string`	none	NO
default	Object to set methods options.	`object`	`{}`	NO
api	Defined API configurations.	`object`	none	NO
dryRun	Defines if metrics should be output to the logger instead of being send.	`boolean`	`false`	NO
flushInterval	Defines the periodicity of buffer flushes in miliseconds.	`number`	`3000`	NO
flushSize	Defines the maximum buffer size before performing a flush.	`number`	`1000`	NO
namespace	Defines the global namespace.	`string`	`application`	NO
sampleRate	Defines the rate sampling. Should be a number between 1, 100.	`number`	`100`	NO
tags	Defines the global tags.	`object`	`{}`	NO
transport	Defines the transport layer to be used to send metrics. Valid Transports: `udp, api`	`string`	none	YES
host	Defines the host name to where the metrics should be sent. Can also be set inside api.	`string`	`127.0.0.1`	NO
port	Defines the port. Can also be set inside api.	`string`	`2013`	NO
token	Defines the token to be used. Must be set inside api.	`string`	none	NO
timeout	Defines the timeout for the transport layers in miliseconds. Must be set inside api.	`number`	`2000`	NO