Statix v1.2.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
: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 to8125
.:tags
- ([binary]) a list of global tags that will be sent with all metrics. By default this option is not present.
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
Callbacks
Opens the connection to the StatsD-compatible server.
The configuration is read from the configuration for the :statix
application
(both globally and per connection).
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
Same as gauge(key, value, [])
.
Writes to the StatsD gauge identified by key
.
Examples
iex> MyApp.Statix.gauge("cpu_usage", 0.83, [])
:ok
Same as histogram(key, value, [])
.
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
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
Same as measure(key, [], function)
.
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"
Same as set(key, value, [])
.
Writes the given value
to the StatsD set identified by key
.
Examples
iex> MyApp.Statix.set("unique_visitors", "user1", [])
:ok
Same as timing(key, value, [])
.