Statful Client for NodeJS

Statful client for NodeJS written in Javascript. This client is intended to gather metrics and send them to Statful.

Table of Contents

• Supported Versions of NodeJS
• Installation
• Quick Start
• Examples
• Reference
• Authors
• License

Supported Versions of NodeJS

Statful client Version	Tested NodeJS versions
4.x.x	4.4.0, 5.12.0, 6.9.2, 7.10.1, 8.2.0
5.x.x	6.9.2, 7.10.1, 8.2.0, 10.9.0
6.x.x	8.2.0, 8.12.0, 10.12.0, 11.0.0

Installation

$ npm install statful-client --save

Quick start

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

var Statful = require('statful-client');

// Creates an object with the configuration and pass it to the client
var config = {
    app: 'AccountService',
    transport: 'api',
    api: {
        token: 'STATFUL_API_TOKEN'
    },
    tags: { cluster: 'production' }
};
var statful = new Statful(config);

// Send a metric
statful.counter('transactions', 1);

IMPORTANT: This configuration uses the default host and port. You can learn more about configuration in Reference.

Examples

You can find here some useful usage examples of the Statful Client. In the following examples is assumed you have already installed and included Statful Client in your project.

UDP Configuration

Creates a simple UDP configuration for the client.

var Statful = require('statful-client');

var config = {
    app: 'AccountService',
    transport: 'udp',
    host: 'statful-relay.yourcompany.com',
    tags: { cluster: 'production' }
};

var statful = new Statful(config);

HTTP Configuration

Creates a simple HTTP API configuration for the client.

var Statful = require('statful-client');

var config = {
    app: 'AccountService',
    transport: 'api',
    api: {
        token: 'STATFUL_API_TOKEN'
    },
    tags: { cluster: 'production' }
};

var statful = new Statful(config);

Logger configuration

Creates a simple client configuration and adds your favourite logger to the client like Bunyan, Winston or any other you want. Just assure that logger object supports: log, info, warn, debug and error methods.

var Statful = require('statful-client');
var logger = require('your-favourite-logging-lib');

var config = {
    app: 'AccountService',
    transport: 'api',
    api: {
        token: 'STATFUL_API_TOKEN'
    },
    tags: { cluster: 'production' }
};

var statful = new Statful(config, logger);

Defaults Configuration Per Method

Creates a configuration for the client with custom default options per method.

var Statful = require('statful-client');

var config = {
    default: {
        counter: { agg: ['avg'], aggFreq: 180 },
        gauge: { agg: ['first'], aggFreq: 180 },
        timer: { tags: { cluster: 'qa' }, agg: ['count'], aggFreq: 180 }
    },
    tags: { cluster: 'production' },
    api: {
        token: 'STATFUL_API_TOKEN'
    },
    transport: 'api'
}

var statful = new Statful(config);

Mixed Complete Configuration

Creates a configuration defining a value for every available option.

var Statful = require('statful-client');

var config = {
    default: {
        timer: { tags: { cluster: 'qa' }, agg: ['count'], aggFreq: 180 }
    },
    dryRun: true,
    flushInterval: 5000,
    flushSize: 50,
    transport: 'api',
    api: {
        timeout: 300,
        token: 'STATFUL_API_TOKEN'
    },
    namespace: 'application',
    tags: { cluster: 'production' }
}

var statful = new Statful(config);

Add metrics

Creates a simple client configuration and use it to send some metrics.

var Statful = require('statful-client');

var config = {
    app: 'AccountService',
    transport: 'udp',
    host: 'statful-relay.yourcompany.com',
    tags: { cluster: 'production' }
};

var statful = new Statful(config);

// Send three different metrics (gauge, timer and a counter)
statful.gauge('testGauge', 10);
statful.timer('testTimer', 100);
statful.counter('testCounter', 1, { agg: ['first'], aggFreq: 60, namespace: 'sandbox' });

// Metric to be sent with tags
statful.counter('testCounter', 1, {tags: {host: 'localhost', status: 'SUCCESS'}});

Reference

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

Global configuration

The custom options that can be set on config param are detailed below.

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
path	Defines the api path to where the metrics should be sent. Can also be set inside api.	string	/tel/v2.0/metric	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

Methods

// Non Aggregated Metrics
- statful.counter('myCounter', 1, {agg: ['sum']});
- statful.gauge('myGauge', 10, { tags: { host: 'localhost' } });
- statful.timer('myCounter', 200, {namespace: 'sandbox'});
- statful.put('myCustomMetric', 200, {timestamp: '1471519331'});

// Aggregated Metrics
- statful.aggregatedCounter('myCounter', 1, 'avg', 60, { tags: { host: 'localhost' } });
- statful.aggregatedGauge('myGauge', 10, 'avg', 60, { tags: { host: 'localhost' } });
- statful.aggregatedTimer('myCounter', 200, 'avg', 60, {namespace: 'sandbox'});
- statful.aggregatedPut('myCustomMetric', 200, 'avg', 60, {timestamp: '1471519331'});

The methods for non aggregated metrics receive a metric name and a metric value as arguments and send a counter/gauge/timer/custom metric. The methods for aggregated metrics receive a metric name, a metric value, an aggregation and an aggregation frequency (used previously to aggregate the metric) as arguments and send a counter/gauge/timer/custom metric. If the options parameter is omitted, the default values are used. Those methods are truly valuable due to need of ingest already aggregated metrics into Statful (for example from AWS CloudWatch). Read the methods options reference bellow to get more information about the default values.

IMPORTANT: You can only send aggregated metrics with api transport type. Otherwise metrics will be discarded and not be sent.

Description	Default for Counter	Default for Gauge	Default for Timer	Default for Put	Available for Aggregated Methods
agg (array) - Defines the aggregations to be executed. These aggregations are merged with the ones configured globally, including method defaults. Valid Aggregations: avg, count, sum, first, last, p90, p95, p99, min, max	['sum', 'count']	[last]	['avg', 'p90', 'count']	[]	NO
aggFreq (number) - Defines the aggregation frequency in seconds. It overrides the global aggregation frequency configuration. Valid Aggregation Frequencies: 10, 30, 60, 120, 180, 300	10	10	10	10'	NO
namespace (string) - Defines the namespace of the metric. It overrides the global namespace configuration.	application	application	application	application	YES
tags (object) - Defines the tags of the metric. These tags are merged with the ones configured globally, including method defaults.	{}	{}	{ unit: 'ms' }	{}	YES
timestamp (string) - Defines the timestamp of the metric. This timestamp is a POSIX/Epoch time in seconds.	current timestamp	current timestamp	current timestamp	current timestamp	YES

Plugins

It is possible to use plugin with the client.

    var SystemStatsPlugin = require('statful-client').systemStatsPlugin;
    var statful = new Statful(config, log);
    statful.use(new SystemStatsPlugin());

System Stats Plugin

This plugin allows the client to send system-related metrics and/or enrich the user metrics with system tags.

System Stats Plugin Configuration

The custom options that can be set on config param are detailed below.

Option	Display name	Description	Type	Default	Required
bufferFlushLength	.buffler.flush_length	Defines the application global name. If specified sets a global tag app=setValue.	metric	false	NO
timerEventLoop	.timer.event_loop	Object to set methods options.	metric	false	NO
processUptime	.process.uptime	Uptime of the process in miliseconds.	metric	false	NO
processMemoryUsage	process.memory.usage	Process memory usage in bytes.	metric	false	NO
processMemoryUsagePerc	process.memory.usage.perc	Process memory usage percentage. (compared to total OS memory)	metric	false	NO
osUptime	.os.uptime	OS uptime in miliseconds.	metric	false	NO
osTotalMemory	.os.memory.total	OS total memory in bytes.	metric	false	NO
osFreeMemory	os.memory.free	OS free memory in bytes.	metric	false	NO
tagHostname	hostname	Hostname.	tag	false	NO
tagPlatform	platform	Platform.	tag	false	NO
tagArchitecture	architecture	Architecture.	tag	false	NO
tagNodeVersion	node_version	NodeJS Version	tag	false	NO

Authors

Mindera - Software Craft

License

Statful NodeJS Client is available under the MIT license. See the LICENSE file for more information.