0.2.3 • Public • Published


I am a node.js client library for metricsd, a metrics aggregator for Graphite that supports counters, histograms and meters. Metricsd 0.4.2+ is recommended.


Install with npm install metricsd or download if you prefer.


Yeah. It's like statsd, but with more types and less heavy lifting, and thus an expanded protocol. statsd clients are compatible with metricsd, but not vice versa. Sorry. If you wanted to, you could probably implement a compatibility mode.


The library currently exports a factory function that creates an instance of a Metrics object with the given options:

// make a metrics instance (default options are shown)
var metricsd = require('metricsd'),
    metrics = metricsd({
        host: "localhost",
        port: 8125,
        enabled: true,
        log: false,
        logger: console.log,
        prefix: null,
        timeout: 1000

The available options are:

  • host and port - server settings.
  • enabled - set to false if you don't want to send metrics while testing.
  • prefix - if you run more than one environment, machine or module, supply a prefix to identify all metrics from this instance.
  • log - whether to log metrics (using logger) instead of sending them using a socket.
  • logger - console.log-compatible logger.
  • timeout - node-metricsd cleans up the internal socket if it's idle using this timeout (milliseconds), and periodically cleans up Buffers using 10 * timeout (a work-around for 0.6.7 and earlier).
  • socket - you may provide your own dgram socket. If so, timeout is ignored.

The metrics instance exposes the options above as properties: all are read-only with the exception of enabled which may be toggled at any time.


Create a new Counter with metrics.count(name) to track relative values.

  var counter = metrics.count('numThings');;  // +2
  counter.dec();   // -1

Alternatively, write directly to a named counter with convenience functions on metrics itself:

  • metrics.count(name) - create a counter
  •, value) - update a counter by +value
  • metrics.dec(name, value) - update a counter by -value
  • metrics.updateCounter(name, value) - update a counter by +value
  • metrics.deleteCounter(name) - tell metricsd to stop tracking a counter


Create a new Gauge with metrics.gauge(name) to track absolute values that are obtained on a regular basis.

var gauge = metrics.gauge('numThings');
gauge.update(10); // numThings == 10
gauge.update(20); // numThings == 20
gauge.update(5);  // numThings == 5

Alternatively, write directly to a named gauge with convenience functions on metrics itself:

  • metrics.gauge(name) - create a gauge
  • metrics.updateGauge(name, value) - set the named gauge's value
  • metrics.deleteGauge(name) - tell metricsd to stop tracking a gauge


Create a new Histogram with metrics.histogram(name) to track intermittent values and their statistical breakdowns (max, min, mean, median, 75th percentile, etc.). (metricsd does the hard work.)

var histogram = metrics.histogram('numThings');
histogram.update(10); // min, max, mean == 10
histogram.update(20); // min == 10, max == 20, mean == 10
histogram.update(5);  // min == 5, max == 10, mean == 17.5

Alternately, write directly to a named histogram with convenience functions on metrics itself:

  • metrics.histogram(name) - create a histogram
  • metrics.updateHistogram(name, value) - set the named histogram's value
  • metrics.deleteHistogram(name) - tell metricsd to stop tracking a histogram


Create a new Timer with metrics.time(name):

var timer = metrics.time('thingTime');
setTimeout(function() {
  timer.stop();             // thingTime == 10ms (approx)
  assert.ok(timer.stopped); // time should be stopped
}, 10);

Or time a series of related events with metrics.time(name) and timer.lap(name):

var timer = metrics.time('otherTime');
setTimeout(function() {
  timer.lap('otherTime.lap1'); // flushes otherTime.lap1 == 10ms (approx)
  assert.ok(timer.running);    // time should not be stopped
}, 10);
setTimeout(function() {
  timer.lap('otherTime.lap2'); // flushes otherTime.lap2 == 10ms (approx)
  assert.ok(timer.running);    // time should not be stopped
  var duration = timer.stop(); // flushes otherTime == 20ms (approx)
  assert.ok(timer.stopped);    // time should be stopped
}, 20);

You can also pause and resume timers (e.g. if you don't want to include time spent "waiting"):

var timer = metricstime('sporadic');
setTimeout(function() {
  var duration = timer.stop(); // flushes sporadic == 0ms (approx)
}, 10);

Or time an event until a callback with metrics.time(name,callback). Method arguments are passed on untouched:

var callback = metrics.timeCallback('thingTime', function(a, b, c) {
  console.log('thing happened %d,%d,%d', a, b, c); // thing happened 1,2,3
// ... 123ms later
callback(1,2,3); // thingTime == 123ms

Timers start automatically, but can be restarted by calling timer.start(). You can wrap callbacks yourself with timer.wrap(callback).

To delete a timer, use metrics.deleteHistogram(name). To update a statistical measurement directly, use metrics.updateHistogram(name, value).

Meters / Marks

To mark the occurrence of a named event, use metrics.mark(name). This is useful for measuring event rates (e.g. requests per second).

To tell metricsd to stop tracking a meter, use metrics.deleteMeter(name).

Raw Metrics

To send a raw metric with no formatting or prefixes applied, use metrics.write(metric). This is used internally by all other metrics. See metricsd for more info on formatting.

Console Output

Specify log: true to emit metrics to STDOUT rather than the default UDP socket.

If you provide a logger to the metricsd() factory (console.log or compatible), it will be used to emit metric strings in the form metric: <metric>. This can be convenient if your logs streams are being consumed by something that can more efficiently funnel data into metricsd or similar.

var metricsd = require('metricsd'),
    metrics = metricsd({
      log: true,
      logger: console.log


Copyright (c) 2012-2013 Seth Fitzsimmons and Tom Carden

Published under the MIT License.




Package Sidebar


npm i metricsd

Weekly Downloads






Last publish


  • mojodna