Puma Statsd Plugin
Add this gem to your Gemfile with puma and then bundle:
gem "puma" gem "puma-plugin-statsd"
Add it to your puma config:
# config/puma.rb bind "http://127.0.0.1:9292" workers 1 threads 8, 16 plugin :statsd
By default the plugin assumes statsd is available at 127.0.0.1. If that's true in your environment, just start puma like normal:
bundle exec puma
If statsd isn't on 127.0.0.1 or the port is non-standard, you can configure them using optional environment variables:
STATSD_HOST=127.0.0.1 STATSD_PORT=9125 bundle exec puma
metric tags are a non-standard addition to the statsd protocol, supported by the datadog "dogstatsd" server.
Should you be reporting the puma metrics to a dogstatsd server, you can set tags via the following three environment variables.
DD_TAGS: Set this to a space-separated list of tags, using the
datadog agent standard format.
For example, you could set this environment variable to set three datadog tags, and then you can filter by in the datadog interface:
export DD_TAGS="env:test simple-tag-0 tag-key-1:tag-value-1" bundle exec rails server
MY_POD_NAME: Set a
pod_name tag to the metrics. The
environment variable is recommended in the datadog kubernetes setup
documentation, and for puma apps deployed to kubernetes it's very helpful to
have the option to report on specific pods.
You can set it on your pods like this:
env: - name: MY_POD_NAME valueFrom: fieldRef: fieldPath: metadata.name
STATSD_GROUPING: add a
grouping tag to the metrics, with a value equal to
the environment variable value. This is particularly helpful in a kubernetes
deployment where each pod has a unique name but you want the option to group
metrics across all pods in a deployment. Setting this on the pods in a
deployment might look something like:
env: - name: STATSD_GROUPING value: deployment-foo
Bug reports and pull requests are welcome on GitHub at https://github.com/yob/puma-plugin-statsd.
Testing the data being sent to statsd
Start a pretend statsd server that listens for UDP packets on port 8125.
If you've installed the gem in your app:
# only need to install the binstub once bundle binstubs puma-plugin-statsd ./bin/statsd-to-stdout
If you are developing/testing this gem locally:
STATSD_HOST=127.0.0.1 bundle exec puma devtools/config.ru --config devtools/puma-config.rb
Throw some traffic at it, either with curl or a tool like ab:
curl http://127.0.0.1:9292/ ab -n 10000 -c 20 http://127.0.0.1:9292/
Watch the output of the UDP server process - you should see statsd data printed to stdout.
This gem is a fork of the excellent puma-plugin-systemd by Samuel Cochran.
Other puma plugins that were helpful references:
The puma docs were also helpful.
The gem is available as open source under the terms of the MIT License.