Docs » Integrations Guide » Integrations Reference » StatsD

../../_images/integrations_statsd.png StatsD 🔗

DESCRIPTION 🔗

This integration primarily consists of the Smart Agent monitor statsd. Below is an overview of that monitor.

Smart Agent Monitor 🔗

This monitor will receive and aggergate Statsd metrics and convert them to datapoints. It listens on a configured address and port in order to receive the statsd metrics. Note that this monitor does not support statsd extensions such as tags.

Supports Spark 2.2.0 and later.

The monitor supports the Counter, Timer, Gauge and Set types which are dispatched as the SignalFx types counter, gauge, gauge and gauge respectively.

Note that datapoints will get a host dimension of the current host that the agent is running on, not the host from which the statsd metric was sent. For this reason, it is recommended to send statsd metrics to a local agent instance.

Verifying installation 🔗

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

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

Adding dimensions to StatsD metrics 🔗

The StatsD monitor can parse keywords from a statsd metric name by a set of converters that was configured by user.

converters:
  - pattern: "cluster.cds_{traffic}_{mesh}_{service}-vn_{}.{action}"
    ...

This converter will parse traffic, mesh, service and action as dimensions from a metric name cluster.cds_egress_ecommerce-demo-mesh_gateway-vn_tcp_8080.update_success. If a section has only a pair of brackets without a name, it will not capture a dimension.

When multiple converters were provided, a metric will be converted by the first converter with a matching pattern to the metric name.

Formatting metric name 🔗

You can customize a metric name by providing a format string within the converter configuration.

converters:
  - pattern: "cluster.cds_{traffic}_{mesh}_{service}-vn_{}.{action}"
    metric: "{traffic}.{action}"

The metrics which match to the given pattern will be reported to SignalFx as {traffic}.{action}. For instance, metric cluster.cds_egress_ecommerce-demo-mesh_gateway-vn_tcp_8080.update_success will be reported as egress.update_success.

metric is required for a converter configuration. A converter will be disabled if metric is not provided.


## INSTALLATION

This integration is part of the [SignalFx Smart Agent](https://github.com/signalfx/integrations/tree/master/signalfx-agent)
as the `statsd` monitor. You should first deploy the Smart Agent to the
same host as the service you want to monitor, and then continue with the
configuration instructions below.

## CONFIGURATION

To activate this monitor in the Smart Agent, add the following to your
agent config:

monitors: # All monitor config goes under this key

  • type: statsd … # Additional config

**For a list of monitor options that are common to all monitors, see [Common
Configuration](https://github.com/signalfx/signalfx-agent/tree/master/docs/monitors/../monitor-config.md#common-configuration).**

<table border="1" class="docutils">
<thead>
<tr>
<th>Config option</th>
<th>Required</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>listenAddress</code></td>
<td>no</td>
<td><code>string</code></td>
<td>The host/address on which to bind the UDP listener that accepts statsd datagrams (<strong>default:</strong> <code>localhost</code>)</td>
</tr>
<tr>
<td><code>listenPort</code></td>
<td>no</td>
<td><code>integer</code></td>
<td>The port on which to listen for statsd messages (<strong>default:</strong> <code>8125</code>)</td>
</tr>
<tr>
<td><code>metricPrefix</code></td>
<td>no</td>
<td><code>string</code></td>
<td>A prefix in metric names that needs to be removed before metric name conversion</td>
</tr>
<tr>
<td><code>converters</code></td>
<td>no</td>
<td><code>list of objects (see below)</code></td>
<td>A list converters to convert StatsD metric names into SignalFx metric names and dimensions</td>
</tr>
</tbody>
</table>

The **nested** `converters` config object has the following fields:

<table border="1" class="docutils">
<thead>
<tr>
<th>Config option</th>
<th>Required</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>pattern</code></td>
<td>no</td>
<td><code>string</code></td>
<td>A pattern to match against StatsD metric names</td>
</tr>
<tr>
<td><code>metricName</code></td>
<td>no</td>
<td><code>string</code></td>
<td>A format to compose a metric name to report to SignalFx</td>
</tr>
</tbody>
</table>

The agent does not do any built-in filtering of metrics coming out of this
monitor.