Skip to content

statful/statful-relay

Repository files navigation

Statful Relay

NPM version Build Status

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.

Table of Contents

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 and show the memory in usage.

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

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

Authors

Mindera - Software Craft

License

Statful Collector AWS is available under the MIT license. See the LICENSE file for more information.