Statful-relay NPM

Statful Relay

Staful Relay built in NodeJS. This is intended to gather metrics from different sources inside the same network and relays it to a centralized system.

Supported NodeJS Versions

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

Installation

$ npm install -g statful-relay

Quick start

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

$ statful-relay generate-config /etc/statful-relay/conf/

# Update some info in the statful-relay-conf.json: statful api token

$ statful-relay start /etc/statful-relay/conf/statful-relay-conf.json

Examples

You can find here an usage example of the Statful Relay. In the following example are assumed you have already installed the collector globally and followed the Quick Start.

Use a listener for statful metrics and sends them to the public api

{
  "debug": false,
  "listeners": {
    "statful": {
      "port": 2013,
      "address": "127.0.0.1",
      "ipv6": false,
      "stats": false
    }
  },
  "statfulClient": {
    "app": "statful-relay",
    "tags": {
       "env": "readme",
    },
    "transport": "api",
    "api": {
      "token": "STATFUL_API_TOKEN",
      "timeout": 2000,
      "host": "api.statful.com", // Default value
      "port": 443 // Default value
    },
    "flushSize": 1000,
    "flushInterval": 3000,
    "systemStats": false
  },
  "bunyan": {
    "name": "stdout",
    "streams": []
  }
}

Reference

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

CLI

$ statful-relay generate-config <path>

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

$ statful-relay start <path>

Starts the relay with the config on given path.

$ statful-relay start-managed <path>

Starts the relay managed by pm2 with the config on given path.

$ statful-relay stop-managed

Stops the relay managed by pm2.

$ statful-relay restart-managed

Restarts the relay managed by pm2.

$ statful-relay help

Shows a small help for the collector.

Configuration

In the configuration file you can find three main sections: debug, listeners, statfulClient and bunyan.

Debug If enabled, Statful-Relay will expose an Http Server on port 9000 to download heapdumps.

Route	Description	Type
/heapdump	Download heapdump.	`gzip`
/memory	Shows the memory in usage.	`string`

Listeners

At the moment we only support one kind of listener called statful. However, here are the reference for listeners.

Option	Description	Type	Default	Required
address	Defines the address where the listener should wait for data.	`string`	none	YES
ipv6	Defines where the address' listener is ipv6.	`boolean`	none	YES
port	Define the port where the listener should wait for data.	`number`	none	YES
stats	Defines if the listener's metric stats should be sent.	`boolean`	none	YES

Statful Client

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
systemStats	Enables sending metrics with flush stats.	`boolean`	`true`	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

To get help and information about this specific options please read the Statful Client NodeJS documentation.

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