Statix v1.0.1 Statix behaviour

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/0 function (see the connect/0 callback) and a few functions can be called on it to report metrics to the StatsD-compatible server read from the configuration. Usually, connect/0 is called in your application’s Application.start/2 callback:

def start(_type, _args) do
  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 or nil) all metrics sent to the StatsD-compatible server through the configured Statix connection will be prefixed with the value of this option. If nil, metrics will not be prefixed. Defaults to nil.
  • :host - (binary) the host where the StatsD-compatible server lives. Defaults to "127.0.0.1".
  • :port - (integer) the port (on :host) where the StatsD-compatible server is running. Defaults to 8125.

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.

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.

Summary

Callbacks

Opens the connection to the StatsD-compatible server

Same as decrement(key, 1, [])

Same as decrement(key, value, [])

Decrements the StatsD counter identified by key by the given value

Same as gauge(key, value, [])

Writes to the StatsD gauge identified by key

Same as histogram(key, value, [])

Writes value to the histogram identified by key

Same as increment(key, 1, [])

Same as increment(key, value, [])

Increments the StatsD counter identified by key by the given value

Same as measure(key, [], function)

Measures the execution time of the given function and writes that to the StatsD timing identified by key

Same as set(key, value, [])

Writes the given value to the StatsD set identified by key

Same as timing(key, value, [])

Writes the given value to the StatsD timing identified by key

Types

key()
key :: iodata
on_send()
on_send :: :ok | {:error, term}
options()
options :: [sample_rate: float, tags: [String.t]]

Callbacks

connect()
connect :: :ok

Opens the connection to the StatsD-compatible server.

The configuration is read from the configuration for the :statix application (both globally and per connection).

decrement(key)
decrement(key) :: on_send

Same as decrement(key, 1, []).

decrement(key, value)
decrement(key, value :: number) :: on_send

Same as decrement(key, value, []).

decrement(key, value, options)
decrement(key, value :: number, options) :: on_send

Decrements the StatsD counter identified by key by the given value.

Works same as increment/3 but subtracts value instead of adding it. For this reason value should be zero or negative.

Examples

iex> MyApp.Statix.decrement("open_connections", 1, [])
:ok
gauge(key, value)
gauge(key, value :: String.Chars.t) :: on_send

Same as gauge(key, value, []).

gauge(key, value, options)
gauge(key, value :: String.Chars.t, options) :: on_send

Writes to the StatsD gauge identified by key.

Examples

iex> MyApp.Statix.gauge("cpu_usage", 0.83, [])
:ok
histogram(key, value)
histogram(key, value :: String.Chars.t) :: on_send

Same as histogram(key, value, []).

histogram(key, value, options)
histogram(key, value :: String.Chars.t, options) :: on_send

Writes value to the histogram identified by key.

Not all StatsD-compatible servers support histograms. An example of a such server statsite.

Examples

iex> MyApp.Statix.histogram("online_users", 123, [])
:ok
increment(key)
increment(key) :: on_send

Same as increment(key, 1, []).

increment(key, value)
increment(key, value :: number) :: on_send

Same as increment(key, value, []).

increment(key, value, options)
increment(key, value :: number, options) :: on_send

Increments the StatsD counter identified by key by the given value.

value is supposed to be zero or positive and decrement/3 should be used for negative values.

Examples

iex> MyApp.Statix.increment("hits", 1, [])
:ok
measure(key, function)
measure(key, function :: (() -> result)) :: result when result: var

Same as measure(key, [], function).

measure(key, options, function)
measure(key, options, function :: (() -> result)) :: result when result: var

Measures the execution time of the given function and writes that to the StatsD timing identified by key.

This function returns the value returned by function, making it suitable for easily wrapping existing code.

Examples

iex> MyApp.Statix.measure("integer_to_string", [], fn -> Integer.to_string(123) end)
"123"
set(key, value)
set(key, value :: String.Chars.t) :: on_send

Same as set(key, value, []).

set(key, value, options)
set(key, value :: String.Chars.t, options) :: on_send

Writes the given value to the StatsD set identified by key.

Examples

iex> MyApp.Statix.set("unique_visitors", "user1", [])
:ok
timing(key, value)
timing(key, value :: String.Chars.t) :: on_send

Same as timing(key, value, []).

timing(key, value, options)
timing(key, value :: String.Chars.t, options) :: on_send

Writes the given value to the StatsD timing identified by key.

value is expected in milliseconds.

Examples

iex> MyApp.Statix.timing("rendering", 12, [])
:ok