happn-stats v1.0.8

happn-stats

Lightweight application monitoring. Works with all versions of nodejs.

Includes CLI with plugin functionality. See example/plugin or happn-stats-elasticsearch.

npm install happn-stats --global
happn-stats -h

Includes Client and Server APIs

const happnStats = require('happn-stats');
const StatsClient = happnStats.StatsClient;
const StatsServer = happnStats.StatsServer;

class StatsClient

This is the clientside metrics collection agent. It has methods for incrementing counters and setting gauge values to be sent to StatsServer instance.

new StatsClient(options)

• options
  • host \ IP address or hostname of StatsServer (default localhost)
  • port \ Optional port at which StatsServer is listening (default 49494)
  • name \ Optional name of this client instance (default untitled).
• Returns \

statsClient.stop()

Stops the client. This closes the websocket and clears some timers.

statsClient.increment(counterName, value)

• counterName \ The name of the counter to increment.
• value \ Optional value to increment by (default 1)

Counters are auto created when incremented.

statsClient.gauge(gaugeName, value)

• gaugeName \ The name of the gauge to set.
• value \ The value to set.

Guages are auto created when set.

Example1

const StatsClient = require('happn-stats').StatsClient;

const statsClient = new StatsClient({
  host: '172.44.1.2' // to StatsServer instance
});

statsClient.increment('counter_name');
statsClient.gauge('gauge_name', 0.5);

// at app shutdown
statsClient.stop();

class StatsServer

This is the serverside metrics collection and aggregation agent. It reports counter and gauge metrics from all connected clients.

new StatsServer(options)

• options
  • host \ Optional address to listen (default 0.0.0.0)
  • port \ Optional port to listen (default 49494)
  • reportInterval \ Optional interval in milliseconds to emit reports (default 10000)
  • fragmentsPerReport \ Optional fragments per report interval (default 5)
• Returns \

The reportInterval and fragmentsPerReport control how frequently the clients send collected metrics to the server. The default will be every 10000 / 5 milliseconds.

StatsServer is an EventEmitter with the following events.

Event: 'report'

• timestamp \ The time of the report as EPOCH milliseconds
• metrics
  • counters \ The aggregated list of counters with per-second values.
  • gauges \ The aggregated list of gauges with values.

This event is emitted every reportInterval. Counters are aggregated into per-second values. Counters that have gone silent at the clients remain in the report with 0 values. Gauges that have gone silent at the clients remain in the report at their last known value.

Event: 'fragment'

• data
  • id \ Internal id of the client from which this aggregation fragment originated.
  • name \ Name of the client as configured in StatsClient constructor.
  • timestamp \ Remote starting time of fragment
  • period \ Time in milliseconds over which the metrics in this fragment were collected
  • metrics\ The metrics

This event is emitted with every metrics fragment arriving from the each client.

statsServer.start()

• Returns \ Resolves with server instance.

Start the server.

statsServer.stop()

• Return \

Stops the server.

statsServer.clear()

Clears all metrics.