Writer for StatsD-compatible servers.

To get started with Statix, you have to create a module that calls use Statix, like this:

defmodule MyApp.Statix do
  use Statix
end

This will make MyApp.Statix a Statix connection that implements the Statix behaviour. This connection can be started with the MyApp.Statix.connect/1 function (see the connect/1 callback) and a few functions can be called on it to report metrics to the StatsD-compatible server read from the configuration. Usually, connect/1 is called in your application's Application.start/2 callback:

def start(_type, _args) do
  :ok = MyApp.Statix.connect()

  # ...
end

Configuration

Statix can be configured either globally or on a per-connection basis.

The global configuration will affect all Statix connections created with use Statix; it can be specified by configuring the :statix application:

config :statix,
  prefix: "sample",
  host: "stats.tld",
  port: 8181

The per-connection configuration can be specified by configuring each specific connection module under the :statix application:

config :statix, MyApp.Statix,
  port: 8123

The following is a list of all the supported options:

• :prefix - (binary) all metrics sent to the StatsD-compatible server through the configured Statix connection will be prefixed with the value of this option. By default this option is not present.
• :host - (binary) the host where the StatsD-compatible server is running. Defaults to "127.0.0.1".
• :port - (integer) the port (on :host) where the StatsD-compatible server is running. Defaults to 8125.
• :tags - ([binary]) a list of global tags that will be sent with all metrics. By default this option is not present. See the "Tags" section for more information.
• :pool_size - (integer) number of ports used to distribute the metric sending. Defaults to 1. See the "Pooling" section for more information.

By default, the configuration is evaluated once, at compile time. If you plan on changing the configuration at runtime, you must specify the :runtime_config option to be true when calling use Statix:

defmodule MyApp.Statix do
  use Statix, runtime_config: true
end

Tags

Tags are a way of adding dimensions to metrics:

MyApp.Statix.gauge("memory", 1, tags: ["region:east"])

In the example above, the memory measurement has been tagged with region:east. Not all StatsD-compatible servers support this feature.

Tags could also be added globally to be included in every metric sent:

config :statix, tags: ["env:#{Mix.env()}"]

Sampling

All the callbacks from the Statix behaviour that accept options support sampling via the :sample_rate option (see also the options/0 type).

MyApp.Statix.increment("page_view", 1, sample_rate: 0.5)

In the example above, the UDP packet will only be sent to the server about half of the time, but the resulting value will be adjusted on the server according to the given sample rate.

Pooling

Statix transmits data using ports.

If a port is busy when you try to send a command to it, the sender may be suspended and some blocking may occur. This becomes more of an issue in highly concurrent environments.

In order to get around that, Statix allows you to start multiple ports, and randomly picks one at the time of transmit.

This option can be configured via the :pool_size option:

config :statix, MyApp.Statix,
  pool_size: 3