statful-client

Statful client for NodeJS applications. This client is intended to gather metrics and send them to Statful.

Showing:

Popularity

Downloads/wk

390

GitHub Stars

8

Maintenance

Last Commit

7mos ago

Contributors

17

Package

Dependencies

3

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

Statful Client for NodeJS

NPM version Build Status

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

Statful Client versionTested NodeJS versions
4.x.x4.4.0, 5.12.0, 6.9.2, 7.10.1, 8.2.0
5.x.x6.9.2, 7.10.1, 8.2.0, 10.9.0
6.x.x8.2.0, 8.12.0, 10.12.0, 11.0.0

Installation

First, install Statful’s NodeJS Client into your System, in the same path as your JS file, by executing the below command:

$ npm install statful-client --save

Quick Start

After installing Statful’s NodeJS Client, you are ready to push your metric into Statful by adding the below code into your JS file:

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

// Creates an object with the desired 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 `counter` metric
statful.counter('transactions', 1);

IMPORTANT:
host / port: Default values are set for host and port, based on whether the 'transport' attribute is set to udp or api. (Refer the below table for the default values). However, it is possible to override the default values, by manually specifying the desired values within the Object (udp or api as applicable)
token: Your token value is available in the 'Api Tokens' page of your Statful account.

[More configurations are available in the Examples section].

Reference

The following section presents a detailed reference of the available options to take full advantage of Statful.

Global Configuration

Below you can find the information on the custom options to set up the configurations parameters.

OptionDescriptionTypeDefaultRequired
appDefines the application's global name. When specified, it sets a global tag like app=setValue.stringnoneNO
defaultObject for setting methods' options.object{}NO
apiObject for setting API configurations: authentication and timeout.objectnoneNO
dryRunDefines if metrics should be output to the logger instead of being sent to Statful (useful for testing/debugging purposes).booleanfalseNO
flushIntervalDefines the periodicity of buffer flushes in milliseconds.number3000NO
flushSizeDefines the maximum buffer size before performing a flush, in milliseconds.number1000NO
namespaceDefines the global namespace. A prefix could be set if the user sends metrics through Statful.stringapplicationNO
sampleRateDefines the rate sampling. It should be a number between [1, 100].number100NO
tagsObject for setting the global tags.object{}NO
transportDefines the transport layer to be used to send metrics.

Valid Transports: udp, api
stringnoneYES
hostDefines the hostname to where the metrics are sent. It can be set for api or udp based on the 'transport' value.stringudp: 127.0.0.1
api: 'api.statful.com'
NO
pathDefines the API path to where the metrics are sent. It can only be set inside api.string/tel/v2.0/metricNO
portDefines the port where the metrics are sent. It can be set for api or udp based on the 'transport' value.stringudp: 2013
api: 443
NO
tokenDefines the token used to match incoming data to Statful. It can only be set inside api.stringnoneYES
timeoutDefines the timeout for the transport layers in milliseconds. It can only be set inside api.number2000NO

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 value as arguments and send a counter, a gauge, a timer or a custom metric.

The methods for aggregated metrics receive a metric name and value, an aggregation and an aggregation frequency (the one used beforehand to aggregate the metric) as arguments, and send a counter, a gauge, a timer or a custom metric. Whenever the options parameter is left out, the default values are used instead.

The latter methods are a valuable asset to address the need of ingestion of already aggregated metrics into Statful (for example, aggregated metrics from AWS CloudWatch). For more information about the default values, read the methods options' reference presented next.

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

DescriptionDefault for CounterDefault for GaugeDefault for TimerDefault for PutAvailable for Aggregated Methods
agg (array) - Defines the aggregations to execute. 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
10101010NO
namespace (string) - Defines the namespace of the metric. It overrides the global namespace configuration.applicationapplicationapplicationapplicationYES
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 UNIX Epoch time, represented in seconds.current timestampcurrent timestampcurrent timestampcurrent timestampYES

Plugins

System Stats Plugin

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

It is possible to use this plugin with the client as follows:

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

System Stats Plugin Configuration

The custom options available to set on config param are detailed below.

OptionDisplay nameDescriptionTypeDefaultRequired
bufferFlushLength.buffler.flush_lengthLength of the queue on flush eventsnumbernoneNO
timerEventLoop.timer.event_loopTime spent to execute the callback in millisecondsnumbernoneNO
processUptime.process.uptimeUptime of the process in millisecondsnumbernoneNO
processMemoryUsageprocess.memory.usageProcess memory usage in bytesnumbernoneNO
processMemoryUsagePercprocess.memory.usage.percProcess memory usage in percentage (compared to total OS memory)numbernoneNO
osUptime.os.uptimeOS uptime in millisecondsnumbernoneNO
osTotalMemory.os.memory.totalOS total memory in bytesnumbernoneNO
osFreeMemoryos.memory.freeOS free memory in bytesnumbernoneNO
tagHostnamehostnameHostnamestringnoneNO
tagPlatformplatformPlatformstringnoneNO
tagArchitecturearchitectureArchitecturestringnoneNO
tagNodeVersionnode_versionNodeJS VersionstringnoneNO

Examples

Here you can find some useful usage examples of the Statful’s NodeJS Client. In the following examples, we assume that you have already installed and included the Statful Client in your project with success.

UDP Configuration

Create 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

Create 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

Create a simple client configuration to add your favorite logger to the client such as Bunyan, Winston or others. The only requirement is to make sure that the chosen 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);

Configuration of Defaults per Method

Create a configuration for the client where you define 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);

Preset Configuration

Create a configuration where you define a value for currently available options.

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);

Send Metrics Configuration

Create a simple client configuration to send a few 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 counter)
statful.gauge('testGauge', 10);
statful.timer('testTimer', 100);
statful.counter('testCounter', 1, { agg: ['first'], aggFreq: 60, namespace: 'sandbox' });

// Send a metric with custom tags
statful.counter('testCounter', 1, {tags: {host: 'localhost', status: 'SUCCESS'}});

Authors

Mindera - Software Craft

License

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

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial