jeffweiss / plug_statsd

Send connection response time and count to statsd

PlugStatsd

Description

A plug for automatically sending timing and count metrics to statsd.

This plug can currently can use any of these statsd backends:

• ex_statsd
• statsderl
• statix

If you have additional statsd clients you'd like added, please open an issue and let me know.

Usage

Add the plug and your chosen statsd backend as a dependencies for your application.

defp deps do
  [
    {:plug_statsd, "~> 0.3"},
    {:ex_statsd, "~> 0.5"},
  ]
end

You should also update your applications list to include the statsd plug and the backend:

def application do
  [applications: [:plug_statsd, :ex_statsd]]
end

Add the plug to your endpoints, here's an example from a Phoenix chat application (lib/chat/endpoint.ex)

defmodule Chat.Endpoint do
...

  plug Plug.Logger

  #send connection request timing and counts to statsd
  plug Plug.Statsd

...
end

Configure your statsd backend (ex_statsd or statderl) using Mix.Config as usual (probably in your config/):

use Mix.Config

config :ex_statsd,
  host: "your.statsd.host.com", # This is optional and will default to 127.0.0.1
  port: 1234,                   # This is optional and will default to 8125
  namespace: "your-app"         # This is optional and will default to nil
config :plug_statsd,
  metrics: [
    # custom_text.4xx.more_custom_text
    {:timer, ["custom_text", :generalized_http_status, "more_custom_text"]},
    # request.GET.api-v1-users-jeff=weiss
    {:counter, ["request", &Plug.Statsd.http_method/2, :uri], sample_rate: 0.1},
    # or this is equivalent as request.GET.api-v1-users-jeff=weiss
    {:counter, ["request", {Plug.Statsd, :http_method}, :uri], sample_rate: 0.1},
  ],
  slash_replacement: "-", # defaults to "."
  dot_replacement: "="    # defaults to "_"

You can also add custom dynamic segments to your metric name by creating a 2-arity function that takes a Plug.Conn and a Keyword list.

Seeing it in action

If you don't immediately have a statsd server available, you can run socat in a terminal.

$ socat UDP-RECV:8125 STDOUT

Depending on your sample rates, you should see a series of output that looks something like

custom_text.2xx.more_custom_text:27|ms
request.GET.[root]:1|c
custom_text.2xx.more_custom_text:18|ms
request.GET.[root]:1|c
custom_text.2xx.more_custom_text:32|ms
request.GET.[root]:1|c
custom_text.4xx.more_custom_text:1|ms
request.GET.api-v1-users-jeff=weiss:1|c
custom_text.4xx.more_custom_text:0|ms
request.GET.api-v1-users-jeff=weiss:1|c

plug_statsd's Issues

Available data and options

Hi, is there a list of the available options e.g. sample_rate.. and the available metrics e.g. generalized_http_status, http_method... etc?

Allow configurable order and content of metric name

We should have a way that users can customize the aspects and order of the metric names that are sent to statsd. For example, if we don't care about HTTP verb, then including GET, POST, PUT, etc in our metrics will only be noise.
Each metric should have a type too.

Here's what I'm thinking for the configuration:

config :plug_statsd,
  metrics: [
    # timing.GET.api.v1.users.jeff_weiss
    {:timer,   ["timing", :http_method, :uri]},
    # response.4xx.403.PATCH.api.v1.users.jeff_weiss
    {:counter, ["response", :generalized_http_status, :http_status, http_method, :uri]},
  ]

Allow configurable replacements for / and .

It turns out that while statsd is just fine with / in the metric name, Graphite doesn't like it.
We should allow users to configure with which characters they'd like their URIs delimited.

Example:

GET /api/v1/messages/3

would, by default, become a metric of

GET.api.v1.messages.3

but if the delimiter were -, the metric would become

GET.api-v1-messages-3

Similarly, we should translate the URI so that portions with a . are treated within statsd/Graphite as subelements.
Example:

GET /api/v1/users/jeff.weiss

would become

GET.api.v1.users.jeff_weiss

but if the delimiter were -, the metric would become

GET.api.v1.users.jeff-weiss

ex-statsd must be required manually

Hi,
I had to add ex-statsd to the mix.exs file manually to get it to load - the dependency wasn't fetched by plug-statsd.
Any ideas why that was the case? It is expected to be fetched by this plug, right?

StatsD client independence

ExStatsD is just slow and most of the times statsderl performs way better, there is even a new kid on the block Statix.
How do you feel about making PlugStatsd independent of any StatsD client and provide configuration parameter for it?

Write some GD tests