A node.js client for Etsy's StatsD server and Datadog's DogStatsD server.
This client will let you fire stats at your StatsD server from a node.js application.
node-statsd Runs and is tested on Node 0.6+ on all *nix platforms and 0.8+ on all platforms including Windows.
$ npm install node-statsd
All initialization parameters are optional.
Parameters (specified as an options hash):
host
: The host to send stats todefault: localhost
port
: The port to send stats todefault: 8125
prefix
: What to prefix each stat name withdefault: ''
suffix
: What to suffix each stat name withdefault: ''
globalize
: Expose this StatsD instance globally?default: false
cacheDns
: Cache the initial dns lookup to hostdefault: false
mock
: Create a mock StatsD instance, sending no stats to the server?default: false
global_tags
: Optional tags that will be added to every metricdefault: []
All StatsD methods other than event have the same API:
name
: Stat namerequired
value
: Stat valuerequired except in increment/decrement where it defaults to 1/-1 respectively
sampleRate
: Sends only a sample of data to StatsDdefault: 1
tags
: The Array of tags to add to metricsdefault: []
callback
: The callback to execute once the metric has been sent
If an array is specified as the name
parameter each item in that array will be sent along with the specified value.
The event method has the following API:
title
: Event titlerequired
text
: Event descriptiondefault is title
options
: Options for the eventdate_happened
Assign a timestamp to the eventdefault is now
hostname
Assign a hostname to the event.aggregation_key
Assign an aggregation key to the event, to group it with some others.priority
Can be ‘normal’ or ‘low’default: normal
source_type_name
Assign a source type to the event.alert_type
Can be ‘error’, ‘warning’, ‘info’ or ‘success’default: info
tags
: The Array of tags to add to metricsdefault: []
callback
: The callback to execute once the metric has been sent
var StatsD = require('node-statsd'),
client = new StatsD();
// Timing: sends a timing command with the specified milliseconds
client.timing('response_time', 42);
// Increment: Increments a stat by a value (default is 1)
client.increment('my_counter');
// Decrement: Decrements a stat by a value (default is -1)
client.decrement('my_counter');
// Histogram: send data for histogram stat
client.histogram('my_histogram', 42);
// Gauge: Gauge a stat by a specified amount
client.gauge('my_gauge', 123.45);
// Set: Counts unique occurrences of a stat (alias of unique)
client.set('my_unique', 'foobar');
client.unique('my_unique', 'foobarbaz');
// Event: sends the titled event
client.event('my_title', 'description');
// Incrementing multiple items
client.increment(['these', 'are', 'different', 'stats']);
// Sampling, this will sample 25% of the time the StatsD Daemon will compensate for sampling
client.increment('my_counter', 1, 0.25);
// Tags, this will add user-defined tags to the data
client.histogram('my_histogram', 42, ['foo', 'bar']);
// Using the callback
client.set(['foo', 'bar'], 42, function(error, bytes){
//this only gets called once after all messages have been sent
if(error){
console.error('Oh noes! There was an error:', error);
} else {
console.log('Successfully sent', bytes, 'bytes');
}
});
// Sampling, tags and callback are optional and could be used in any combination
client.histogram('my_histogram', 42, 0.25); // 25% Sample Rate
client.histogram('my_histogram', 42, ['tag']); // User-defined tag
client.histogram('my_histogram', 42, next); // Callback
client.histogram('my_histogram', 42, 0.25, ['tag']);
client.histogram('my_histogram', 42, 0.25, next);
client.histogram('my_histogram', 42, ['tag'], next);
client.histogram('my_histogram', 42, 0.25, ['tag'], next);
Some of the functionality mentioned above is specific to DogStatsD and will not do anything if are using the regular statsd client. This includes:
- global_tags parameter
- tags parameter
- histogram API
- event API
In the event that there is a socket error, node-statsd
will allow this error to bubble up. If you would like to catch the errors, just attach a listener to the socket property on the instance.
client.socket.on('error', function(error) {
return console.error("Error in socket: ", error);
});
If you want to catch errors in sending a message then use the callback provided.
node-statsd is licensed under the MIT license.