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
// make a metrics instance (default options are shown)var metricsd =metrics =;
The available options are:
port- server settings.
enabled- set to
falseif you don't want to send metrics while testing.
prefix- if you run more than one environment, machine or module, supply a
prefixto identify all metrics from this instance.
log- whether to log metrics (using
logger) instead of sending them using a socket.
timeout- node-metricsd cleans up the internal socket if it's idle using this timeout (milliseconds), and periodically cleans up
10 * timeout(a work-around for 0.6.7 and earlier).
socket- you may provide your own dgram socket. If so,
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
metrics.count(name) to track relative values.
var counter = metrics;counter; // +2counter; // -1
Alternatively, write directly to a named counter with convenience functions on
metrics.count(name)- create a counter
metrics.inc(name, 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
metrics.gauge(name) to track absolute values that
are obtained on a regular basis.
var gauge = metrics;gauge; // numThings == 10gauge; // numThings == 20gauge; // numThings == 5
Alternatively, write directly to a named gauge with convenience functions on
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
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; // min, max, mean == 10histogram; // min == 10, max == 20, mean == 10histogram; // min == 5, max == 10, mean == 17.5
Alternately, write directly to a named histogram with convenience functions on
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
var timer = metrics;;
Or time a series of related events with
var timer = metrics;;;
You can also pause and resume timers (e.g. if you don't want to include time spent "waiting"):
var timer = ;timer;;
Or time an event until a callback with
arguments are passed on untouched:
var callback = metrics;// ... 123ms later; // thingTime == 123ms
Timers start automatically, but can be restarted by calling
You can wrap callbacks yourself with
To delete a timer, use
metrics.deleteHistogram(name). To update a statistical
measurement directly, use
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
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.
log: true to emit metrics to
STDOUT rather than the default UDP
If you provide a
logger to the
metricsd() factory (
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 =metrics =;
Copyright (c) 2012-2013 Seth Fitzsimmons and Tom Carden
Published under the MIT License.