hot-shots
A Node.js client for Etsy's StatsD server, Datadog's DogStatsD server, and InfluxDB's Telegraf StatsD server.
This project is a fork off of node-statsd. This project includes all changes in node-statsd, all open PRs to node-statsd when possible, and some additional goodies (like Telegraf support, child clients, TypeScript types, and more).
Installation
$ npm install hot-shots
Migrating from node-statsd
You should only need to do one thing: change node-statsd to hot-shots in all requires.
You may also want to use the Datadog events support in here instead of other libraries. You can also check the detailed change log for what has changed since the last release of node-statsd.
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
cacheDns
: Cache the initial dns lookup to host default: false
mock
: Create a mock StatsD instance, sending no stats to the server? default: false
globalTags
: Tags that will be added to every metric. Can be either an object or list of tags. default: {}
maxBufferSize
: If larger than 0, metrics will be buffered and only sent when the string length is greater than the size. default: 0
bufferFlushInterval
: If buffering is in use, this is the time in ms to always flush any buffered metrics. default: 1000
telegraf
: Use Telegraf's StatsD line protocol, which is slightly different than the rest default: false
sampleRate
: Sends only a sample of data to StatsD for all StatsD methods. Can be overriden at the method level. default: 1
errorHandler
: A function with one argument. It is called to handle various errors. default: none
, errors are thrown/logger to consoleuseDefaultRoute
: Use the default interface on a Linux system. Useful when running in containers
All StatsD methods other than event and close have the same API:
name
: Stat name required
value
: Stat value required except in increment/decrement where it defaults to 1/-1 respectively
sampleRate
: Sends only a sample of data to StatsD default: 1
tags
: The tags to add to metrics. Can be either an object { tag: "value"}
or an array of tags. default: []
callback
: The callback to execute once the metric has been sent or buffered
If an array is specified as the name
parameter each item in that array will be sent along with the specified value.
The close method has the following API:
callback
: The callback to execute once close is complete. All other calls to statsd will fail once this is called.
The event method has the following API:
title
: Event title required
text
: Event description default is title
options
: Options for the event
date_happened
Assign a timestamp to the event default 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 tags to add to metrics. Can be either an object { tag: "value"}
or an array of tags. default: []
callback
: The callback to execute once the metric has been sent.
The check method has the following API:
name
: Check name required
status
: Check status required
options
: Options for the check
date_happened
Assign a timestamp to the check default is now
hostname
Assign a hostname to the check.message
Assign a message to the check.
tags
: The tags to add to metrics. Can be either an object { tag: "value"}
or an array of tags. default: []
callback
: The callback to execute once the metric has been sent.
var StatsD = require('hot-shots'),
client = new StatsD();
client.socket.on('error', function(error) {
console.error("Error in socket: ", error);
});
client.timing('response_time', 42);
var fn = function(a, b) { return a + b };
client.timer(fn, 'fn_execution_time')(2, 2);
client.increment('my_counter');
client.decrement('my_counter');
client.histogram('my_histogram', 42);
client.gauge('my_gauge', 123.45);
client.set('my_unique', 'foobar');
client.unique('my_unique', 'foobarbaz');
client.event('my_title', 'description');
client.check('service.up', client.CHECKS.OK, { hostname: 'host-1' }, ['foo', 'bar'])
client.increment(['these', 'are', 'different', 'stats']);
client.increment('my_counter', 1, 0.25);
client.histogram('my_histogram', 42, ['foo', 'bar']);
client.set(['foo', 'bar'], 42, function(error, bytes){
if(error){
console.error('Oh noes! There was an error:', error);
} else {
console.log('Successfully sent', bytes, 'bytes');
}
});
client.histogram('my_histogram', 42, 0.25);
client.histogram('my_histogram', 42, { tag: 'value'}]);
client.histogram('my_histogram', 42, ['tag:value']);
client.histogram('my_histogram', 42, next);
client.histogram('my_histogram', 42, 0.25, ['tag']);
client.histogram('my_histogram', 42, 0.25, next);
client.histogram('my_histogram', 42, { tag: 'value'}, next);
client.histogram('my_histogram', 42, 0.25, { tag: 'value'}, next);
var childClient = client.childClient({
prefix: 'additionalPrefix.',
suffix: '.additionalSuffix',
globalTags: { globalTag1: 'forAllMetricsFromChildClient'}
});
childClient.increment('my_counter_with_more_tags');
client.close(function(err) {
console.log('The close did not work quite right: ', err);
});
DogStatsD and Telegraf functionality
Some of the functionality mentioned above is specific to DogStatsD or Telegraf. They will not do anything if you are using the regular statsd client.
- globalTags parameter- DogStatsD or Telegraf
- tags parameter- DogStatsD or Telegraf.
- telegraf parameter- Telegraf
- histogram method- DogStatsD or Telegraf
- event method- DogStatsD
- check method- DogStatsD
Errors
As usual, callbacks will have an error as their first parameter. You can have an error in both the message and close callbacks.
If the optional callback is not given, an error is thrown in some cases and a console.log message is used in others. An error will only be thrown when there is a missing callback if it is some potential configuration issue to be fixed.
In the event that there is a socket error, hot-shots
will allow this error to bubble up unless an errorHandler
is specified. If you would like to catch the errors, either specify an errorHandler
in your root client or just attach a listener to the socket property on the instance.
var client = new StatsD({
errorHandler: function (error) {
console.log("Socket errors caught here: ", error);
}
})
client.socket.on('error', function(error) {
console.error("Error in socket: ", error);
});
Submitting changes
Thanks for considering making any updates to this project! Here are the steps to take in your fork:
- Run "npm install"
- Add your changes in your fork as well as any new tests needed
- Run "npm test"
- Update README.md with any needed documentation
- If you have made any API changes, update types.d.ts
- Push your changes and create the PR
When you've done all this we're happy to try to get this merged in right away.
Name
Why is this project named hot-shots? Because:
- It's impossible to find another statsd name on npm
- It's the name of a dumb movie
- No good reason
License
hot-shots is licensed under the MIT license.