metricsd
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.
metricsd?
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.
Usage
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 = metrics = ;
The available options are:
host
andport
- server settings.enabled
- set tofalse
if you don't want to send metrics while testing.prefix
- if you run more than one environment, machine or module, supply aprefix
to identify all metrics from this instance.log
- whether to log metrics (usinglogger
) 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 upBuffer
s using10 * 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.
Counters
Create a new Counter
with metrics.count(name)
to track relative values.
var counter = metrics; counter; // +2 counter; // -1
Alternatively, write directly to a named counter with convenience functions on
metrics
itself:
metrics.count(name)
- create a countermetrics.inc(name, value)
- update a counter by +valuemetrics.dec(name, value)
- update a counter by -valuemetrics.updateCounter(name, value)
- update a counter by +valuemetrics.deleteCounter(name)
- tell metricsd to stop tracking a counter
Gauges
Create a new Gauge
with 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
itself:
metrics.gauge(name)
- create a gaugemetrics.updateGauge(name, value)
- set the named gauge's valuemetrics.deleteGauge(name)
- tell metricsd to stop tracking a gauge
Histograms
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; // 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
itself:
metrics.histogram(name)
- create a histogrammetrics.updateHistogram(name, value)
- set the named histogram's valuemetrics.deleteHistogram(name)
- tell metricsd to stop tracking a histogram
Timers
Create a new Timer
with metrics.time(name)
:
var timer = metrics; ;
Or time a series of related events with metrics.time(name)
and
timer.lap(name)
:
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 metrics.time(name,callback)
. Method
arguments are passed on untouched:
var callback = metrics; // ... 123ms later; // 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 = metrics = ;
License
Copyright (c) 2012-2013 Seth Fitzsimmons and Tom Carden
Published under the MIT License.