numbat-powered metrics emitter


Numbat-powered metrics emitter. See numbat-collector for the matching metrics collector.

var Emitter = require('numbat-emitter');
var emitter = new Emitter({
    uri: 'tcp://localhost:8000',
    app: 'www',
    node: 'www:8081'
emitter.metric({ name: 'httpd.latency', value: 30 });
emitter.metric({ name: 'disk.used.percent', value: 36 });
emitter.metric({ name: 'heartbeat'});

See the examples/ directory for working examples.

The constructor requires an options object with an app name in the app field and some manner of specifying where to emit the metrics. You can specify the protocol, host, and port in handy url-parseable format: tcp://, udp://localhost:5000, socket:/tmp/foozle.sock. Do this in the uri field of the options object.

Config options:

uriuri of the metrics collectoreither this or path
pathpath to the unix domain socket where the collector is listeningeither this or uri
appname of this service or app; every metric name will be prefixed with ity
nodename of this specific app instance
maxretriesnumber of times to retry connecting before giving up100
maxbacklogmax number of metrics to hold in backlog during reconnects1000

An example:

    uri:  'udp://localhost:8000',
    app: 'udp-emitter',
    node: 'emitter-1',
    maxretries: 10,
    maxbacklog: 200,

Or numbat might be listening via a unix domain socket:

    path: '/tmp/numbat-collector.sock',
    app: 'socket-emitter'

Valid events look like this:

    name: 'name.of.metric',
    value: 42
    status: 'okay' | 'warning' | 'critical' | 'unknown',
    description: 'textual description',
    ttl: ms-to-live,
    // fields provided for you 
    app: 'appname-from-options',
    host: os.hostname(),
    time: ts-in-ms,

You can add any fields you like & they will be persisted in InfluxDB. However, only the fields listed above are meaningful to the analyzer. Those fields are described in detail below.

NOTE: You can of course emit any events you like! The style of events required/expected by numbat's analyzer, however, might change in development.

String. Required. Name of this event or metric. Use dots . to separate namespaces. If you do not prefix the metric name with yourapp., numbat will do this for you.

Number. Optional. Timestamp in milliseconds since the epoch. If you do not pass a time field, one will be created for you with

Number. Optional. The value of this metric, if appropriate. If you do not pass a value field, it will be defaulted to 1.

String. Optional. One of okay, warning, critical, or unknown. Use this to trigger alerts if this event represents a known-bad condition.

Textual description of the event. Max 255 bytes. Optional.

Number. Optional. Milliseconds that this event is considered valid. The analyzer will expire the event after event.time + event.ttl.

See also the example emitter in example.js.

var e1 = {
    name: 'request.latency',
    value: 42
    status: 'okay',
var e2 = {
    name: 'request.latency',
    value: 5023
    status: 'warning',
var e3 = { name: 'heartbeat', ttl: 30000 };

Sure! Write tests with Lab & must. Use BSD/Allman bracing or I will stare at you funny and not take your pull request.