SourcesStatsd

The statsd source accepts etsy/statsd encoded payloads. This source will listen on both IPv4 and IPv6 UDP sockets with configurable port. The mapping of statsd lines into cernan's internal model is straightforward but does require an understanding of the statsd protocol. The basic statsd line is:

METRIC_NAME:[+|-]VALUE|TYPE[@SAMPLE]

That is, a metric name is separated from its value by a colon and the value may or may not be signed. The value is separated from the line-type by a pipe and the type may or may not be followed by a sample rate for the value. The types are:

• c -- counter -- summation in a windowed interval
• g -- gauge -- set or summation, depending on the sign of the value
• ms -- timer -- windowed percentiles
• h -- histogram -- windowed percentiles

In order, these map as follows:

• c => Telemetry: ephemeral, SUM
• g, signed => Telemetry: persisted, SUM
• g, unsigned => Telemetry: persisted, SET
• ms => Telemetry: empherial, SUMMARIZE | HISTOGRAM
• h => Telemetry: ephemeral, SUMMARIZE | HISTOGRAM

Configuration

The statsd source configuration options are as follows:

• enabled :: whether the source is enabled [default: true]
• port :: the port for the source to listen on, both IPv4 and IPv6 [default: 8125]
• forwards :: the filters and/or sinks to forward into [default: []]
• summarize_error_bound :: configure the error boundary of summary types [default: 0.001] (SINCE 0.8.0)
• mapping :: ARRAY (see below)

The forward concept is described in detail here.

You may configure multiple statsd sources.

Mapping

As alluded to in the statsd source documentation statsd timers and statsd histograms may be mapped to different cernan aggregations, either SUMMARIZE or HISTOGRAM. The mapping array controls this mapping. Each member of the array is a table with the following options:

• mask :: metrics with names that regex match mask will be mapped
• bounds :: sets the upper limit of the histogram bins

If a timer or histogram metric does not match a mapping that metric will be interpreted as a SUMMARIZE metric. If a metric would match multiple mappings then the mapping listed first in configuration will be the one it matches.

Example

[sources]
  [sources.statsd.primary]
  enabled = true
  port = 8125
  forwards = []

  [sources.statsd.primary.mapping]
  [sources.statsd.primary.mapping.foo_bar]
  mask = "foo.bar.*"
  bounds = [0.0, 10.0, 1000.0]

  [sources.statsd.primary.mapping.default]
  mask = ".*"
  bounds = [0.0, 0.1, 10.0, 100.0]

  [sources.statsd.secondary]
  enabled = true
  port = 8126
  forwards = []

  [sources.statsd.disabled]
  enabled = false
  port = 8127
  forwards = []

This enables three statsd sources 'primary', 'secondary' and 'disabled'. Only 'primary' and 'secondary' are enabled. The 'primary' statsd source has mappings which match "foo.bar.*" specifically and a catch-all. The primary statsd source will interpret all timers and histograms as HISTOGRAM.