A StatsD backend for Librato Metrics
$ cd /path/to/statsd $ npm install statsd-librato-backend
You have to add the following basic configuration information to your StatsD config file.
librato:email: "firstname.lastname@example.org"token: "ca98e2bc23b1bfd0cbe9041e824f610491129bb952d52ca4ac22cf3eab5a1c32"source: "unique-per-statsd-instance"
Example Full Configuration File:
librato:email: "email@example.com"token: "ca98e2bc23b1bfd0cbe9041e824f610491129bb952d52ca4ac22cf3eab5a1c32"source: "unique-per-statsd-instance"backends: "statsd-librato-backend"port: 8125
The email and token settings can be found on your Librato account settings page. The source is an optional-but-recommended string to use as a source for all measurements from this statsd instance. This should be unique for each statsd process. If unset, the source will default to the node's hostname.
statsd-librato-backend backend to the list of StatsD
backends in the StatsD configuration file:
Start/restart the statsd daemon and your StatsD metrics should now be pushed to your Librato account.
The Librato backend also supports the following optional configuration
options under the top-level
the source name from the metric name. The first
capturing group of the regex is used as the source name,
and everything not matched will be the metric name.
Example formats: "SOURCE.METRIC" => /^([^\.]+)\./ "METRIC.SOURCE" => /\.([^\.]+)$/ "server.SOURCE.METRIC" => /^server\.([^\.]+)\./
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 to Librato as gauge values (default) or
as counters. When set to true (default), the
backend will send the aggregate value of all
increment/decrement operations during a flush
period as a gauge measurement to Librato.
When set to false, the backend will track the running value of all counters and submit the current absolute value to Librato as a counter. This will require some additional memory overhead and processing time to track the running value of all counters.
skipInternalMetrics: Boolean of whether to skip publishing of
internal statsd metrics. This includes all
metrics beginning with 'statsd.' and the
metric numStats. Defaults to true, implying
they are not sent.
retryDelaySecs: How long to wait before retrying a failed
request, in seconds.
postTimeoutSecs: Max time for POST requests to Librato, in
that match any of the regular expressions will be sent to Librato.
Defaults to an empty array.
includeMetrics: /^my\.included\.metrics/ /^my.specifically.included.metric$/
any of the regular expressions will NOT be sent to Librato. If includedMetrics
is specified, then patterns will be matched against the resulting
list of included metrics.
Defaults to an empty array.
Metrics which are sent to StatsDThis will exclude metrics sent to StatsD so that metrics which match the specified regex value
excludeMetrics: /^my\.excluded\.metrics/ /^my.specifically.excluded.metric$/
globalPrefix: A string to prepend to all measurement names sent to Librato. If set, a dot will automatically be added as separator between prefix and measurement name.
By default StatsD will push a zero value for any counter that does not receive an update during a flush interval. Similarly, it will continue to push the last seen value of any gauge that hasn't received an update during the flush interval. This is required for some backend systems that can not handle sporadic metric reports and therefore require a fixed frequency of incoming metrics. However, it requires StatsD to track all known gauges and counters and means that published payloads are inflated with zero-fill data.
Librato can handle sporadic metric publishing at non-fixed frequencies. Any "zero filling" of graphs is handled at display time on the frontend. Therefore, when using the Librato backend it is beneficial for bandwidth and measurement-pricing costs to reduce the amount of data sent to Librato. In the StatsD configuration file it is recommended that you enable the following top-level configuration directive to reduce the amount of zero-fill data StatsD sends:
You can configure your metric in Librato to display the gaps between sporadic reports in a variety of ways. Visit the knowledge base article to see how to change the display attributes.
All metrics sent by the statsd server will use the source name
configured in the global configuration file. You can also set a source
name on a per-stat basis by leveraging the
configuration option. The statsd protocol only supports a single name
string per stat, so to specify a source name you have to include it
in the stat name. The
sourceRegex option sets a regular expression
filter that splits the source and metric names from the single statsd
For example, to prefix your stat name with a source name separated by
a period, you would use the
Sending a stat name of web-prod-23.api-requests.2xx would use a metric name of api-requests.2xx and a source name of web-prod-23.
Unfortunately, the set of characters that you can use to delimit
source from metric is limited to:
[a-zA-Z_\-0-9\.]. The statsd
daemon will substitute any characters not in that set before passing
the stat to the Librato backend.
You can push metrics to Graphite and Librato simultaneously as
you evaluate Librato. Just include both backends in the
backends: "./backends/graphite" "statsd-librato-backend"
See the statsd manpage for more information.
If you want to use statsd-librato-backend througth a proxy you should install https-proxy-agent module:
$npm install https-proxy-agent
After that you should add the proxy config to the StatsD config file in the librato configuration section:
"librato" :"proxy" :"uri" : ""
That configuration will proxy requests via a proxy listening on localhost on port 8080. You can also use an https proxy by setting the protocol to https in the URI.
If you are upgrading from the statsd-librato-backend before version 0.1.0, the default representation for counter metrics has changed. Starting with 0.1.0, statsd counters are now represented as Librato gauges by default. If you were using the default configuration prior to 0.1.0, then you may run into conflicts when you try to push statsd counter metrics to Librato as gauges. To fix this, you have two options:
Keep the prior behavior of sending statsd counters as Librato
counters. Just set the
countersAsGauges configuration variable to
false in your statsd config.
After upgrading to 0.1.0, remove all counter metrics that were
published by statsd. You can use the API pattern DELETE route to mass
delete metrics. To delete only counter metrics, add the parameter
If you want to contribute: