# README
Statsd plugin for DC/OS Metrics
This plugin will forward all data received by dcos-metrics to a statsd server, as defined by STATSD_HOST and STATSD_PORT environment variables.
Architecture
The statsd plugin uses the dcos-metrics plugin API. You run the 'plugin' (a slight misnomer; it is in fact a separate binary) on each node in your cluster. It polls its local HTTP API for metrics, which it re-transmits to your statsd server.
Limitations
- statsd has no units, therefore units are not sent
- statsd has no tags, therefore dimensions are not sent
- statsd only accepts integer values, therefore metrics are rounded to the nearest integer
- statsd assigns its own timestamps when metrics are received, therefore timestamps do not precisely reflect the moment the measurement occurred
- dcos-metrics has no concept of timers or counters, therefore all datapoints are sent as gauges
Usage
Installing and starting the plugin
- Download the latest statsd plugin binary from the releases page
- Upload the binary as
/opt/mesosphere/bin/dcos-metrics-statsd-plugin
on every node in your cluster - Download the environment file
- Upload the environment file to
/opt/mesosphere/etc
on every node - On every master node:
- Copy the master systemd service file to
/etc/systemd/system
- Reload the systemd state by running
systemctl daemon-reload
- Start the systemd service with
systemctl start dcos-metrics-statsd-master
- Copy the master systemd service file to
- On every agent node:
- Copy the agent systemd service file to
/etc/systemd/system
- Reload the systemd state by running
systemctl daemon-reload
- Start the systemd service with
systemctl start dcos-metrics-statsd-agent
- Copy the agent systemd service file to
Running a statsd server on a DC/OS cluster
If you installed the plugin according to the steps above, you can simply deploy the statsd server application with Marathon. The simplest way to do that is using the CLI command
dcos marathon app add statsd-server.json
You can also deploy it manually with the DC/OS UI.
This will start a Docker container with a statsd server configured and ready to go. You can configure your own routing using marathon-haproxy or edge-LB, or you can VPN into your cluster using the dcos tunnel command, after which you can find the Graphite UI at:
http://statsd-server.marathon.l4lb.thisdcos.directory
Please note that this configuration is neither highly available nor persistent; you will need to adapt it if you want those attributes.
Configuring the plugin to use your own statsd server
If you'd prefer to configure your own statsd server (or already have one set up), you'll need to pass its address to the plugin. This requires modifying the systemd environment file on every node.
- Download the environment file
- Modify the
STATSD_UDP_HOST
andSTATSD_UDP_PORT
EVs to your desired value - Upload the environment file to
/opt/mesosphere/etc
on every node - Reload systemd state by running
systemctl daemon-reload
on every node - Restart the systemd services by running
systemctl restart dcos-metrics-statsd-agent
on the agent nodes andsystemctl restart dcos-metrics-statsd-master
on the master nodes
Testing your setup
Followed the steps above, but not sure you've done it right?
Launch the statsd-emitter test task on Marathon:
dcos marathon app add statsd-emitter.json
Then check your statsd frontend for the 'statsd_tester.time.uptime' metric - if it is present, you have configured it correctly.