search

brightcove / hot-shots

Node.js client for statsd, DogStatsD, and Telegraf
MIT License
527 stars 135 forks source link

readme

hot-shots

A Node.js client for Etsy's StatsD server, Datadog's DogStatsD server, and InfluxDB's Telegraf StatsD server.

This project was originally a fork off of node-statsd. This project includes all changes in the latest node-statsd and many additional changes, including:

You can read about all changes in the changelog.

hot-shots supports Node 10.x and higher.

Build Status

Usage

All initialization parameters are optional.

Parameters (specified as one object passed into hot-shots):

StatsD methods

All StatsD methods other than event, close, and check have the same API:

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

close

The close method has the following API:

event

The event method has the following API:

check

The check method has the following API:

  var StatsD = require('hot-shots'),
      client = new StatsD({
          port: 8020,
          globalTags: { env: process.env.NODE_ENV },
          errorHandler: errorHandler,
      });

  // 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 (DataDog and Telegraf only)
  client.histogram('my_histogram', 42);

  // Distribution: Tracks the statistical distribution of a set of values across your infrastructure.
  // (DataDog v6)
  client.distribution('my_distribution', 42);

  // Gauge: Gauge a stat by a specified amount
  client.gauge('my_gauge', 123.45);

  // Gauge: Gauge a stat by a specified amount, but change it rather than setting it
  client.gaugeDelta('my_gauge', -10);
  client.gaugeDelta('my_gauge', 4);

  // 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 (DataDog only)
  client.event('my_title', 'description');

  // Check: sends a service check (DataDog only)
  client.check('service.up', client.CHECKS.OK, { hostname: 'host-1' }, ['foo', 'bar'])

  // Incrementing multiple items
  client.increment(['these', 'are', 'different', 'stats']);

  // Incrementing with tags
  client.increment('my_counter', ['foo', 'bar']);

  // 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
  // (DataDog and Telegraf only)
  client.histogram('my_histogram', 42, ['foo', 'bar']);

  // Using the callback.  This is the same format for the callback
  // with all non-close calls
  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');
    }
    });

  // Timing: sends a timing command with the specified milliseconds
  client.timing('response_time', 42);

  // Timing: also accepts a Date object of which the difference is calculated
  client.timing('response_time', new Date());

  // Timer: Returns a function that you call to record how long the first
  // parameter takes to execute (in milliseconds) and then sends that value
  // using 'client.timing'.
  // The parameters after the first one (in this case 'fn')
  // match those in 'client.timing'.
  var fn = function(a, b) { return a + b };
  client.timer(fn, 'fn_execution_time')(2, 2);

  // Async timer: Similar to timer above, but you instead pass in a function
  // that returns a Promise.  And then it returns a Promise that will record the timing.
  var fn = function () { return new Promise(function (resolve, reject) { setTimeout(resolve, n); }); };
  var instrumented = statsd.asyncTimer(fn, 'fn_execution_time');
  instrumented().then(function() {
    console.log('Code run and metric sent');
  });

  // Async timer: Similar to asyncTimer above, but it instead emits a distribution.
  var fn = function () { return new Promise(function (resolve, reject) { setTimeout(resolve, n); }); };
  var instrumented = statsd.asyncDistTimer(fn, 'fn_execution_time');
  instrumented().then(function() {
    console.log('Code run and metric sent');
  });

  // Sampling, tags and callback are optional and could be used in any combination (DataDog and Telegraf only)
  client.histogram('my_histogram', 42, 0.25); // 25% Sample Rate
  client.histogram('my_histogram', 42, { tag: 'value'}); // User-defined tag
  client.histogram('my_histogram', 42, ['tag:value']); // Tags as an array
  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: 'value'}, next);
  client.histogram('my_histogram', 42, 0.25, { tag: 'value'}, next);

  // Use a child client to add more context to the client.
  // Clients can be nested.
  var childClient = client.childClient({
    prefix: 'additionalPrefix.',
    suffix: '.additionalSuffix',
    globalTags: { globalTag1: 'forAllMetricsFromChildClient'}
  });
  childClient.increment('my_counter_with_more_tags');

  // Close statsd.  This will ensure all stats are sent and stop statsd
  // from doing anything more.
  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.

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 explicitly thrown when there is a missing callback or if it is some potential configuration issue to be fixed.

If you would like to ensure all errors are caught, specify an errorHandler in your root client. This will catch errors in socket setup, sending of messages, and closing of the socket. If you specify an errorHandler and a callback, the callback will take precedence.

// Using errorHandler
var client = new StatsD({
  errorHandler: function (error) {
    console.log("Socket errors caught here: ", error);
  }
})

Congestion error

If you get an error like Error sending hot-shots message: Error: congestion with an error code of 1, it is probably because you are sending large volumes of metrics to a single agent/ server. This error only arises when using the UDS protocol and means that packages are being dropped. Take a look at the Datadog docs for some tips on tuning your connection.

Unix domain socket support

The 'uds' option as the protocol is to support Unix Domain Sockets for Datadog. It has the following limitations:

The above will cause the underlying library that is used, unix-dgram, to not install properly. Given the library is listed as an optionalDependency, and how it's used in the codebase, this install failure will not cause any problems. It only means that you can't use the uds feature.

Submitting changes

Thanks for considering making any updates to this project! This project is entirely community-driven, and so your changes are important. Here are the steps to take in your fork:

  1. Run "npm install"
  2. Add your changes in your fork as well as any new tests needed
  3. Run "npm test"
  4. Update README.md with any needed documentation
  5. If you have made any API changes, update types.d.ts
  6. 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.

Package versioning and security

Versions will attempt to follow semantic versioning, with major changes only coming in major versions.

npm publishing is possible by one person, bdeitte, who has two-factor authentication enabled for publishes. Publishes only contain one additional library, unix-dgram.

License

hot-shots is licensed under the MIT license.