Docs » Integrations Guide » Integrations Reference » StatsD

image0 StatsD

Metadata associated with the StatsD collectd plugin can be found here. The relevant code for the plugin can be found here.


The StatsD plugin for collectd listens for StatsD events, aggregates them and transmits them according to collectd’s configuration. Use this plugin to send data from StatsD to SignalFx.

From collectd’smanpage:

The statsd plugin listens to a UDP socket, reads “events” in the statsd protocol and dispatches rates or other aggregates of these numbers periodically.

The plugin implements the Counter, Timer, Gauge and Set types which are dispatched as the collectd types derive, latency, gauge and objects respectively.

For more information about StatsD, see


This plugin requires:

Software Version
collectd 5.4+


NOTE: This plugin is included by default with all versions of the SignalFx collectdagent.

  1. Download SignalFx’s sample StatsD configuration file to /etc/collectd/managed_config.
  2. Restart collectd.

Verifying installation

You can send StatsD metrics locally with netcat as follows, then verify in SignalFx that the metric arrived.

$ echo "statsd.test:1|g" | nc -w 1 -u 8125


SignalFx’s example configuration file for this plugin can be used as-is, without modification. To read more about available configuration options, see collectd’s manpage for thisplugin.

Deployment options

SignalFx recommends deploying the SignalFx collectdagent, including this plugin, on every host that is reporting StatsD metrics. Having done so, configure all StatsD clients to direct metrics from individual reporters to localhost, on the port specified in 10-statsd.conf (by default: 8125). In this scenario, all metrics are aggregated locally, reducing network traffic.

This plugin can also listen for and aggregate StatsD metrics from remote hosts. By default, SignalFx’s default configuration of the StatsD plugin only opens the StatsD port for local processes. To listen for StatsD metrics sent from remote hosts, configure the StatsD plugin to open the port publicly by modifying 10-statsd.conf as follows:

LoadPlugin statsd
<Plugin statsd>
 Host "" # changed from ""
 DeleteSets true
 TimerPercentile 90.0
 TimerLower true
 # ...


Adding dimensions to StatsD metrics

Add dimensions to your metrics by adding key-value pairs to your StatsD metric names as follows:

$ echo "statsd.[foo=bar,dim=val]test:1|g" | nc -w 1 -u 8125

This creates a metric called statsd.test of type gauge, with dimensions foo=bar and dim=val.

StatsD’s python API allows you to construct your StatsClient with a prefix. This can simplify the configuration of dimensions.

The examples below produce the same metric and dimensions.

>>> c = statsd.StatsClient('localhost', 8125, prefix="test[dim1=val1]")
>>> c.gauge("gaugor", 400)


>>> c = statsd.StatsClient('localhost', 8125, prefix="test")
>>> c.gauge("[dim1=val1]gaugor", 400)

Note that you may specify dimensions by adding bracketed key-value pairs either in the prefix, or on each metric, but not both. If bracketed dimension sections are included in both the prefix and metric name, SignalFx will use the one specified in the metric name.

The following example produces a metric called test.gaugor of type gauge, with dimension foo=bar. Dimension dim=val, specified in the prefix, is ignored.

>>> c = statsd.StatsClient('localhost', 8125, prefix="test[dim=val]")
>>> c.gauge("[foo=bar]gaugor", 400)

Using StatsD metrics in SignalFx

SignalFx supports using the components of dot-delimited metric names as dimensions for the purposes of filtering and aggregation in a chart. Click here to read more.

Deleting unused metric names from collectd’s internal cache

SignalFx’s default configuration for this plugin sets all Delete[Type]s configuration options to True. We strongly recommend this in order to ensure that metrics that have stopped reporting are not reported as 0 in perpetuity. Setting these parameters to False results in collectd’s memory usage increasing over time, as the set of metrics reported from StatsD grows indefinitely. This is especially important in environments that are long-running or whose metrics change frequently.