dogstatsd-node

A node.js client for Etsy's StatsD server extended with Datadog's histogram and tags.

Most of the code (including parts of this readme) is copied directly from the excellent https://github.com/sivy/node-statsd (v0.0.7), and the datadog parts wrote in by looking at https://github.com/joybro/node-dogstatsd, but with an added twist in the API.

IMPORTANT: This is not a drop-in replacement for node-statsd or node-dogstatsd, the API has changed.

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. (So this should work too.)

Usage

All initialization parameters are optional.

Parameters (specified as an options hash):

• host: The host to send stats to default: localhost
• port: The port to send stats to default: 8125
• prefix: What to prefix each stat name with default: ''
• suffix: What to suffix each stat name with default: ''
• globalize: Expose this StatsD instance globally? default: false
• dnsCache: Cache the initial dns lookup to host default: false
• mock: Create a mock StatsD instance, sending no stats to the server? default: false

All StatsD/DataDog methods have the same API:

• name: Stat name required
• value: Stat value required except in increment/decrement where it defaults to 1/-1 respectively

which returns a Stat Object which can sent by calling .send() on them. Additional options to the stat maybe chained by calling stat.sampleRate(value).tags(['x:1']) before sending.

If an array is specified as the name parameter each item in that array will be sent along with the specified value.

1  var StatsD = require('dogstatsd-node').StatsD,
2      client = new StatsD();
3
4  // Timing: sends a timing command with the specified milliseconds
5  client.timing('response_time', 42).send();
6
7  // Increment: Increments a stat by a value (default is 1)
8  client.increment('my_counter').send();
9
10  // Decrement: Decrements a stat by a value (default is -1)
11  client.decrement('my_counter').send();
12
13  // Gauge: Gauge a stat by a specified amount
14  client.gauge('my_gauge', 123.45).send();
15
16  // Histogram: Datadog's histogram
17  client.histogram('histogram', 10).send();
18
19  // Set: Counts unique occurrences of a stat (alias of unique)
20  client.set('my_unique', 'foobar').send();
21  client.unique('my_unique', 'foobarbaz').send();
22
23  // Incrementing multiple items
24  client.increment(['these', 'are', 'different', 'stats']).send();
25
26  // Sampling, this will sample 25% of the time the StatsD Daemon will compensate for sampling
27  client.increment('my_counter', 1).sampleRate(0.25).send();
28
29  // Datadog's Tags
30  client.increment('my_counter', 1).tags(['host:xyz']).send();
31
32  // Using the callback
33  client.set(['foo', 'bar'], 42).send(function(error, bytes){
34    //this only gets called once after all messages have been sent
35    if(error){
36      console.error('Oh noes! There was an error:', error);
37    } else {
38      console.log('Successfully sent', bytes, 'bytes');
39    }
40  });

Errors

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.

1client.socket.on('error', function(error) {
2  return console.error("Error in socket: ", error);
3});

If you want to catch errors in sending a message then use the callback provided.

License

node-statsd is licensed under the MIT license. So is this.