nvoy

nvoy is a tool for batching up AWS CloudWatch Metrics and sending them to AWS. It runs in the background of any node app and emits the metrics after a configurable amount of time has passed. The benefits of this are:

• Reduces AWS costs by reducing the number of PUTs.
• Circumvents AWS limits on the number of metrics that can be sent per second. This is especially useful for high volume applications, which create a large amount of metrics.
• Reduces network traffic and other resource needs of applications.

API Reference

For more detailed documentation, you can view the full API reference as generated by jsdocs.

Install

npm install nvoy

or

npm install nvoy --save

Components

There are a number of components that make up nvoy. To get started, all you need is the AwsMetricsEmitter. There are also a number of supporting components that can save you a lot of time.

Core

Component	Description
AwsMetricsEmitter	This is the main class to create a metrics emitter and to add metrics to the buffer.
AwsMetricsBuffer	Child component of the emitter. Stores the metrics before they are flushed to AWS.

Supporting

Component	Description
ServiceMetricsEmitter	Inherits from AwsMetricsEmitter and contains shortcut methods for service based metrics.
WebMetricsEmitter	Inherits from AwsMetricsEmitter and contains shortcut methods for web-based metrics.

AWS Credentials

You will need to configure your credentials through the aws cli, environment variables or another means for the emitter to work.

Logging

The AwsMetricsEmitter constructor takes a winston logger or signature matching equivalent for the purposes of logging.

AWS Metrics Emitter

Prerequisites

The AWS Emitter requires a winston logger to be passed in.

const winston = require('winston');

Create AWS Emitter

When creating an aws emitter, there are a number of options that need to be passed into the constructor. There is additionally an option to pass through a cloud watch object to help with testing, but for most cases, you will want to pass in null.

Unlike the shortcut classes ServiceMetricsEmitter and WebMetricsEmitter, the namespace used for metrics must be fully specified when adding them.

const { AwsMetricsEmitter } = require('nvoy');

// options
const batchDelay = 60000; // Metrics sent every 60 seconds
const autoStart = false;
const logger = winston.createLogger();

// create emitter
const awsMetricsEmitter = new AwsMetricsEmitter(batchDelay, autoStart, null, logger);

// start emitter
awsMetricsEmitter.start(); // not needed if autoStart = true

Add Metrics

WARNING: There is a maximum size limit on the request of putting metrics. Be sure to make sure your aggregated metrics do not exceed this. Visit the AWS CloudWatch limits page for more details.

const namespace = `MyOrg/Services/MyService`;
const metricName = 'OkResponses';
const dimensions = [
    { Name: 'Method', Value: 'GET' },
    { Name: 'Environment', Value: 'test' },
];
const unit = 'Count';
const value = 1;
const aggregate = true; // if set to false it will not batch metrics together.

awsMetricsEmitter.buffer.addMetricDatum(namespace, metricName, dimensions, unit, value, aggregate);

Service Metrics Emitter

The Service Metrics emitter acts as a short cute for adding metrics to a REST based service, such as a microservice. It inherits from the AWS Metrics Emitter.

The namespace used for metrics is {self.org}/Services/{appName}.

Prerequisites

These are the same as the AMS Metrics Emitter.

Create Service Metrics Emitter

The Service Metrics Emitter is created in a very similar way to the AWS Metrics emitter, but also requires org and environment to be passed in.

const { ServiceMetricsEmitter } = require('envoy');

// options
const batchDelay = 60000; // Metrics sent every 60 seconds
const autoStart = false;
const org = 'MyOrg';
const environment = 'development';
const cloudWatch = aws.cloudWatch();
const logger = winston.createLogger();

// create emitter
const serviceMetricsEmitter = new AwsMetricsEmitter(batchDelay, autoStart, org, environment, null, logger);

// start emitter
awsMetricsEmitter.start(); // not needed if autoStart = true

Add Metrics

The following example demonstrates the typical metrics you will want to add for every service call:

// options
const serviceName = 'MyService';

// Add one to the number of requests for the service as a whole.
serviceMetricsEmitter.addRequestCountMetric(serviceName);

// Add one to the number of GET requests to the service.
serviceMetricsEmitter.addServiceMethodCountMetric(serviceName, 'GET', 'Requests');

// Add one to the number for GET requests with an OK response.
serviceMetricsEmitter.addServiceMethodCountMetric(serviceName, 'GET', 'OkResponses');

// Meta data about the Request/Rsponse.
serviceMetricsEmitter.addServiceResponseTimeMetric(serviceName, 'GET', 34);
serviceMetricsEmitter.addServiceResponseSizeMetric(serviceName, 'GET', 10);

Supporting Classes

There are a couple of internal classes, which are used by the Service Metrics Emitter. These have been exposed in case they are needed for testing or other purposes.

const { ServiceMetricNames, ServiceMetricMethods } = require('envoy');

ServiceMetricNames.GET() // returns 'GET'
ServiceMetricMethods.BAD_REQUEST_RESPONSES() // returns 'BadRequestResponses'

Web Metrics Emitter

The Web Metrics Emitter is very similar to the Service Metrics Emitter but is more aimed towards non REST service web applications. The main difference is the namespace used for metrics, which is {self.org}/Apps/{appName}.

Prerequisites

These are the same as the AMS Metrics Emitter.

Create Web Metrics Emitter

The Web Metrics Emitter is created in the same way as the Service Metrics Emitter but requires a slightly different object.

const { WebMetricsEmitter } = require('envoy');

Add Metrics

The following example demonstrates the typical metrics you will want to add for every service call:

// options
const appName = 'MyWebApp';
const method = 'GET';

// Add one to the number of requests for the web app as a whole.
webMetricsEmitter.addWebRequestCountMetric(serviceName);

// Add one to the number of GET requests to the web app.
webMetricsEmitter.addWebMethodCountMetric(appName, 'GET', 'Requests');

// Add one to the number for GET requests with an OK response.
webMetricsEmitter.addWebMethodCountMetric(appName, 'GET', 'OkResponses');

// Meta data about the Request/Rsponse.
serviceMetricsEmitter.addResponseTimeMetric(appName, 'GET', 34);
serviceMetricsEmitter.addResponseSizeMetric(appName, 'GET', 10);

Supporting Classes

The Web Metrics Emitter uses the same internal classes as the Service Metrics Emitter.

Test Applications

WARNING: Running the test applications will use AWS resources and you may be charged.

A number of test applications have been bundled into the package to allow for easy testing of metrics within AWS and to make sure you have set up your credentials correctly. These can be installed globally by running -npm install -g. The cli will work on windows, mac and linux.

command	description
nvoy-service-metrics-emitter	emits test service metrics to AWS.

NPX

You can also run the test applications without needing to download or install the package by using npx. For example: npx nvoy nvoy-service-metrics-emitter.

Contributing

nvoy is a new project and looking for people to contribute and help make it better. Please see the document on Contributing.

Please see also our Code of Conduct.

License

Copyright (c) Matthew Bill. All rights reserved.

Licensed under the MIT License.