The LibratoReporter class runs in the background, publishing metrics from dropwizard/metrics to the Librato Metrics API at the specified interval.
<dependency>
<groupId>com.librato.metrics</groupId>
<artifactId>metrics-librato</artifactId>
<version>4.0.1.12</version>
</dependency>
The metrics-librato:4.x.x.x release depends on librato-java:1.x which includes a fix for an issue
that was causing dashes to be stripped from metric names incorrectly. It is recommended to view the readme
for that project before upgrading to understand how some existing metric names might change.
During the initialization of your program, simply use the .enable method with the appropriately configured LibratoReporter.Builder class. See the setters on that method for all the available customizations (there are quite a few). The constructor for the Builder requires only the things that are necessary; sane defaults are provided for the rest of the options.
MetricRegistry registry = environment.metrics(); // if you're not using dropwizard, use your own registry
LibratoReporter.enable(
LibratoReporter.builder(
registry,
"<Librato Email>",
"<Librato API Token>",
"<Source Identifier (usually hostname)>"),
10,
TimeUnit.SECONDS);
Since this project depends heavily on metrics-core, the version number will be <version of metrics-core being depended on>.<release number of the reporter>. Thus, the first release will be version 2.1.2.0, as 2.1.2 is the current stable version of metrics-core. If this proves impractical, a different versioning scheme will be investigated.
This library will output a few different kinds of Librato Metrics to Librato:
- Gauges: a measurement at a point in time
- DeltaGauge: a gauge that submits the delta between the current value of the gauge and the previous value. Note that the reporter will omit the first value for a DeltaGauge because it knows no previous value at that time.
- ComplexGauge: includes sum, count, min, max, and average measurements.See the API documentation for more information on extended gauge parameters.
This section describes how each of the Coda metrics translate into Librato metrics.
Given a Coda Gauge with name foo, the following values are reported:
- Gauge: name=foo
The value reported for the Gauge is the current value of the Coda Gauge at flush time.
Given a Coda Counter with name foo, the following values are reported:
- Gauge: name=foo
The value reported for the Gauge is the current value of the Coda Counter at flush time.
Note: Librato Counters represent monotonically increasing values. Since Coda Counters can be incremented or decremented, it makes sense to report them as Librato Gauges.
Given a Coda Histogram with name foo, the following values are reported:
- ComplexGauge: name=foo
- Gauge: name=foo.median
- Gauge: name=foo.75th
- Gauge: name=foo.95th
- Gauge: name=foo.98th
- Gauge: name=foo.99th
- Gauge: name=foo.999th
- DeltaGauge: name=foo.count (represents the number of values the Coda Histogram has recorded)
Note that Coda Histogram percentiles are determined using configurable Reservoir Sampling. Histograms by default use a non-biased uniform reservoir.
Given a Coda Meter with name foo, the following values are reported:
- DeltaGauge: name=foo.count (represents the number of values the Coda Meter has recorded)
- Gauge: name=foo.meanRate
- Gauge: name=foo.1MinuteRate
- Gauge: name=foo.5MinuteRate
- Gauge: name=foo.15MinuteRate
Coda Timers compose a Coda Meter as well as a Coda Histogram, so the values reported to Librato are the union of the values reported for these two metric types.
Given a Coda Timer with name foo, the following values are reported:
- ComplexGauge: name=foo
- Gauge: name=foo.median
- Gauge: name=foo.75th
- Gauge: name=foo.95th
- Gauge: name=foo.98th
- Gauge: name=foo.99th
- Gauge: name=foo.999th
- DeltaGauge: name=foo.count (represents the number of values the Coda Timer has recorded)
- Gauge: name=foo.meanRate
- Gauge: name=foo.1MinuteRate
- Gauge: name=foo.5MinuteRate
- Gauge: name=foo.15MinuteRate
Note that Coda Timer percentiles are determined using configurable Reservoir Sampling. Coda Timers by default use an exponentially decaying reservoir to prioritize newer data.
While this library aims to accurately report all of the data that Coda Metrics provides, it can become somewhat verbose. One can reduce the number of metrics reported for Coda Timers, Coda Meters, and Coda Histograms when configuring the reporter. The percentiles, rates, and count for these metrics can be whitelisted (they are all on by default). In order to do this, supply a LibratoReporter.MetricExpansionConfig to the builder:
LibratoReporter.builder(<username>, <token>, <source>)
.setExpansionConfig(
new MetricExpansionConfig(
EnumSet.of(
LibratoReporter.ExpandedMetric.PCT_95,
LibratoReporter.ExpandedMetric.RATE_1_MINUTE)))
.build();
In this configuration, the reporter will only report the 95th percentile and 1 minute rate for these metrics. Note that the ComplexGauges will still be reported.
Timers and Histograms end up generating a complex gauge along with any other expanded metrics that are configured to be sent to Librato. If you wish to exclude these complex gauges, one may enable omitComplexGauges in the LibratoReporter.
LibratoReporter.builder(<username>, <token>, <source>)
.setOmitComplexGauges(true)
.build();
Note that in addition to the mean, complex gauges also include the minimum and maximum dimensions, so if you choose to enable this option, you will no longer have access to those summaries for those metrics.
A new feature in 4.0.1.4 detects when certain types of metrics (Meters, Histograms, and Timers) stop getting updated by the application. When this happens, metrics-librato will stop reporting these streams to Librato until they are updated again. Since Librato does not charge for metrics which are not submitted to the API, this can lower your cost, especially for metrics that report infrequently.
This is enabled by default, but should you wish to disable this feature, you can do so when setting up the LibratoReporter:
LibratoReporter.builder(<username>, <token>, <source>)
...
.setDeleteIdleStats(false)
Sources are globally set for the LibratoReporter as described above. Sometimes though it is desirable to use custom sources for certain signals. To do this, supply a sourceRegex to the LibratoReporter builder.
The regular expression must contain one matching group. As metrics-librato takes metrics from the registry and
batches them, it will apply this regular expression (if supplied) to each metric name. If the regular expression
matches, it will use the first matching group as the source for that metric, and everything after the entire
expression match will be used as the actual metric name.
builder.setSourceRegex(Pattern.compile("^(.*?)--"))
The above regular expression will take a meter name like "uid:42--api.latency" and report that with a source of
uid:42 and a metric name of api.latency.
The dropwizard-librato project allows you to send Metrics from within your Dropwizard application to Librato Metrics by adding a section to your config file.