huyl/statsd-librato-backend

A StatsD backend that sends metrics to Librato Metrics

StatsD Librato Metrics backend

Overview

This is a pluggable backend for StatsD, which publishes stats to Librato Metrics.

Requirements

• StatsD versions >= 0.3.0.
• An active Librato Metrics account.

Installation

$ cd /path/to/statsd
$ npm install statsd-librato-backend

Configuration

You have to add the following basic configuration information to your StatsD config file.

{
  librato: {
    email: "myemail@example.com",
    token: "ca98e2bc23b1bfd0cbe9041e824f610491129bb952d52ca4ac22cf3eab5a1c32",
  }
}

Enabling

Add the statsd-librato-backend backend to the list of StatsD backends in the StatsD configuration file:

{
  backends: ["statsd-librato-backend"]
}

Start/restart the statsd daemon and your StatsD metrics should now be pushed to your Librato Metrics account.

Additional configuration options

The Librato backend also supports the following optional configuration options under the top-level librato hash:

• source: An optional source name to use for all measurements. If a metric name contains source value(s) (metric name formatted as: 'metric_name/source1/source2'), the metric specific name will take precedence over this value.

• snapTime: Measurement timestamps are snapped to this interval (specified in seconds). This makes it easier to align measurements sent from multiple statsd instances on a single graph. Default is to use the flush interval time.

• countersAsGauges: A boolean that controls whether StatsD counters are sent as native Librato Metrics counters (default) or as Librato Metrics gauges. The original Librato statsd fork sent StatsD counters as gauges instead of counters, so this provides an easy upgrade path. Defaults to false.

• skipInternalMetrics: Boolean of whether to skip publishing of internal statsd metrics. This includes all metrics beginning with 'statsd.' and the metric numStats. Default false -- they are published to Librato.

Upgrading from the old Librato statsd fork

If you are upgrading from the old Librato statsd fork, then the minimal upgrade steps are:

1. Upgrade to the latest Etsy statsd.
2. In the statsd directory, install the Librato backend: npm install statsd-librato-backend.
3. Swap the statsd configuration variable graphService with the backends list. So if your old configuration looked like:

{
  graphService: "librato-metrics",
  libratoUser: "myemail@example.com",
  libratoApiKey: "ca98e2bc23b1bfd0cbe9041e824f610491129bb952d52ca4ac22cf3eab5a1c32",
  ...
}

Then your new configuration would look like:

{
  backends: ["statsd-librato-backend"],
  libratoUser: "myemail@example.com",
  libratoApiKey: "ca98e2bc23b1bfd0cbe9041e824f610491129bb952d52ca4ac22cf3eab5a1c32",
  ...
}

The Librato backend will automatically detect a legacy configuration file and set countersAsGauges to true to maintain backwards compatibility.

Upgrading to native counters

If you would like to upgrade to native Librato Metrics counters, then you'll need to:

1. Stop all statsd daemons.
2. Switch to the new configuration format listed at the top of this file, ensuring that countersAsGauges is false or not set.
3. Using the UX or API, delete all statsd counters that were originally published as gauges to Librato Metrics.
4. Restart all statsd daemons.

Publishing to Graphite and Librato Metrics simultaneously

You can push metrics to Graphite and Librato Metrics simultaneously as you evaluate Librato. Just include both backends in the backends variable:

{
  backends: [ "./backends/graphite", "statsd-librato-backend" ],
  ...
}

See the statsd manpage for more information.

NPM Dependencies

None

Development

• Librato Metrics Backend

If you want to contribute:

1. Clone your fork
2. Hack away
3. If you are adding new functionality, document it in the README
4. Push the branch up to GitHub
5. Send a pull request