numbat-emitter

numbat-powered metrics emitter

numbat-emitter

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

var Emitter = require('numbat-emitter');
 
var emitter = new Emitter({
    host: 'localhost',
    port: 8000,
    udp: true,
    node: 'www-1'
});
emitter.metric({ name: 'httpd.latency', value: 30 });
emitter.metric({ name: 'disk.used.percent', value: 36 });
emitter.metric({ name: 'heartbeat'});

The constructor requires an options object with a node name in the node 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://collector.example.com:5000, udp://localhost:5000, socket:/tmp/foozle.sock. Do this in the uri field of the options object.

An example:

{
    uri:  'udp://localhost:8000',
    node: 'udp-emitter'
}

You can also specify the destination more verbosely using host and port fields:

{
    host: 'collector.example.com',
    port: 8000,
    node: 'tcp-emitter'
}

If you wish to use udp instead of tcp, pass udp: true:

{
    host: 'localhost',
    port: 8000,
    udp:  true,
    node: 'udp-emitter'
}

And finally a unix domain socket:

{
    path: '/tmp/numbat-collector.sock',
    node: 'socket-emitter'
}

Valid events look like this:

{
    name: 'name.of.metric',
    time: ts-in-ms,
    value: 42
    host: 'hostname.example.com',
    tags: ['array', 'of', 'tags'],
    status: 'okay' | 'warning' | 'critical' | 'unknown',
    description: 'textual description',
    ttl: ms-to-live,
}

You can add any fields you like & they will be persisted in InfluxDB. However, only the fields listed above are meaninful 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.

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

Number. Optional. The value of this metric, if appropriate.

String. Optional. The hostname of the service generating this event, if relevant.

Array of strings. Optional. Use tags to hint to the analyzer/dashboard how to display this metric. Understood metric types include:

  • annotation
  • counter
  • gauge
  • histogram

Tags are not passed on to InfluxDB by the collector.

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
    tags: ['app', 'histogram' ],
    status: 'okay',
};
var e2 = {
    name: 'request.latency',
    value: 5023
    tags: ['app', 'histogram' ],
    status: 'warning',
};
 
var e3 = { name: 'heartbeat', ttl: 30000 };
  • Backlog should be capped at a configurable size so you don't explode memory if your collector is down.

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

ISC