Categorygithub.com/dcos/dcos-metricspluginsstatsd
package
0.0.0-20190227035732-d56806e5335b
Repository: https://github.com/dcos/dcos-metrics.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
9
Dependents
0
Files
113 SLOC

# 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

  1. Download the latest statsd plugin binary from the releases page
  2. Upload the binary as /opt/mesosphere/bin/dcos-metrics-statsd-plugin on every node in your cluster
  3. Download the environment file
  4. Upload the environment file to /opt/mesosphere/etc on every node
  5. On every master node:
    1. Copy the master systemd service file to /etc/systemd/system
    2. Reload the systemd state by running systemctl daemon-reload
    3. Start the systemd service with systemctl start dcos-metrics-statsd-master
  6. On every agent node:
    1. Copy the agent systemd service file to /etc/systemd/system
    2. Reload the systemd state by running systemctl daemon-reload
    3. Start the systemd service with systemctl start dcos-metrics-statsd-agent

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.

  1. Download the environment file
  2. Modify the STATSD_UDP_HOST and STATSD_UDP_PORT EVs to your desired value
  3. Upload the environment file to /opt/mesosphere/etc on every node
  4. Reload systemd state by running systemctl daemon-reload on every node
  5. Restart the systemd services by running
    1. systemctl restart dcos-metrics-statsd-agent on the agent nodes and
    2. systemctl 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.