Dogmatix (Dogmatix v0.1.0) View Source
This module provides the main API to interface with a StasD/DogStatsD agent.
Getting started
A new instance of Dogmatix can be started via the start_link/2
function:
{:ok, pid} = Dogmatix.start_link("my_dogmatix", "localhost", 8125)
This will create a new instance named "my_dogmatix", communicating via UDP with an agent located at localhost:8125
.
This instance will use all the default options.
Instantiation via a custom module
defmodule MyApp.Dogmatix do
use Dogmatix
end
MyApp.Dogmatix.start_link("localhost", 8125)
Your custom module can then be used without having to provide the name of your Dogmatix instance:
MyApp.Dogmatix.increment("my_counter")
Configuration
Various options can be provided to start_link
to configure the instance:
:worker_count
- (positive integer) - number of UDP sockets and workers used to distribute the metrics. Defaults to4
.:prefix
- (binary) - all metrics sent to the agent will be prefixed with this value. Not set by default.:tags
- ([binary]) - a list of tags to be sent with all metrics. Format:["tag1:value1", "tag2:value2"]
. Not set by default.:max_datagram_size
- (integer) - the maximum number of bytes for a message that can be sent. Defaults to1432
.:buffer_flush_ms
- (integer) - metric flush interval in milliseconds. Defaults to500
.
Sending metrics
The module provides the functions to send all the supported metrics, event and service checks to the agent.
All the functions accept the following options:
:tags
- ([binary]) - to add metric specific tags to the global tags:timeout
- (integer) - a timeout value in milliseconds to be used when calling a worker from the pool. Defaults to1000
.
Sampling
All metric-sending functions support a :sample_rate
options. A sample rate is a float between 0 and 1 representing
the percentage of packets that are effectively sent to the agent.
Dogmatix.count("my_dogmatix", "current_users", 1, sample_rate: 0.2)
In the example above, only 20% of the calls will effectively send a packet to the agent. Agents supporting sampling will adjust the value according to the sample rate.
Tagging
Metrics, events and service checks can be tagged to add dimensions to their information. Note that not all agents support this feature.
Constant tags can be defined when instantiating a Dogmatix client:
Dogmatix.start_link("my_dogmatix", "localhost", 8125, tags: ["env:dev"])
In the example above, all metrics, events and service checks sent with this instance will be tagged with "env:dev".
Additionally, all functions support the :tags
option to add ad-hoc tags.
Dogmatix.increment("my_dogmatix", "page_views", tags: ["page:home"])
In the example above, the metric "page_views" will be tagged with both "page:home" (and "env:dev").
Pooling
For each instance of Dogmatix, a pool of worker/socket is started to format and send datagrams. The amount of workers
can be configured via the :worker_count
options when starting the instance.
Metric Buffering
In order to reduce network traffic, Dogmatix supports metric buffering. It attempts to group as many metrics as possible into a single datagram before sending to the agent. This behavior can be configured via two instantiation options:
:max_datagram_size
An integer representing the maximum size in bytes of a datagram. Make sure to configure a size that does not exceed
the Agent-side per-datagram buffer size or the network/OS max datagram size. The default value is 1432
- the largest
possible size given the Ethernet MTU of 1514 bytes.
:buffer_flush_ms
An integer representing in milliseconds the frequency of datagram buffer flush. Each worker/socket maintains its own local buffered datagram, i.e. an accumulation of metrics to be sent once the size of the datagram reaches the maximum possible size of a packet. For the case where your application does not capture metrics frequently, Dogmatix will regularly flush these buffers to make sure that buffered metrics are sent to the agent in a timely manner.
The default value is 500
.
If your application is so "metric intensive" that there is no chance of seeing your metrics lingering in the buffer,
you can disable this behavior completely by setting this option to 0
.
Link to this section Summary
Functions
Returns a specification to start this module under a supervisor.
Changes the counter identified by metric_name
by the given value
.
Decrements the counter identified by metric_name
by 1.
Writes value
to the distribution identified by metric_name
.
Sends the provided event.
Sets the value of the gauge identified by metric_name
to the given value
.
Writes value
to the histogram identified by metric_name
.
Increments the counter identified by metric_name
by 1.
Sends the provided service check.
Writes value
to the set identified by metric_name
.
Starts a new pool of connection to an agent.
Writes value
to the timer identified by metric_name
.
Link to this section Types
Specs
Specs
metric_option() :: {:tags, [binary()]} | {:timeout, non_neg_integer()}
Specs
metric_options() :: [metric_option()]
Specs
metric_result() :: :ok | {:error, binary()}
Specs
Specs
start_option() :: {:worker_count, pos_integer()} | {:prefix, binary()} | {:tags, [binary()]} | {:max_datagram_size, pos_integer()} | {:buffer_flush_ms, non_neg_integer()}
Specs
start_options() :: [start_option()]
Link to this section Functions
Returns a specification to start this module under a supervisor.
See Supervisor
.
Specs
count(id(), binary(), metric_value(), metric_options()) :: metric_result()
Changes the counter identified by metric_name
by the given value
.
Examples
iex> Dogmatix.count("my_dogmatix", "cache_hits", 4)
:ok
Specs
decrement(id(), binary(), metric_options()) :: metric_result()
Decrements the counter identified by metric_name
by 1.
Equivalent to calling count/4
with a value
of -1.
Examples
iex> Dogmatix.decrement("my_dogmatix", "current_users")
:ok
Specs
distribution(id(), binary(), metric_value(), metric_options()) :: metric_result()
Writes value
to the distribution identified by metric_name
.
Examples
iex> Dogmatix.set("my_dogmatix", "response_time", 9)
:ok
Sends the provided event.
Examples
iex> Dogmatix.event("my_dogmatix", %Dogmatix.Event{title: "An error occurred", text: "Error message"})
:ok
Specs
gauge(id(), binary(), metric_value(), metric_options()) :: metric_result()
Sets the value of the gauge identified by metric_name
to the given value
.
Examples
iex> Dogmatix.gauge("my_dogmatix", "disk_usage", 0.75)
:ok
Specs
histogram(id(), binary(), metric_value(), metric_options()) :: metric_result()
Writes value
to the histogram identified by metric_name
.
Examples
iex> Dogmatix.histogram("my_dogmatix", "page_views", 15)
:ok
Specs
increment(id(), binary(), metric_options()) :: metric_result()
Increments the counter identified by metric_name
by 1.
Equivalent to calling count/4
with a value
of 1.
Examples
iex> Dogmatix.increment("my_dogmatix", "page_views")
:ok
Sends the provided service check.
Examples
iex> Dogmatix.event("my_dogmatix", %Dogmatix.ServiceCheck{name: "application_check", status: :ok, message: "All good!"})
:ok
Specs
set(id(), binary(), metric_value(), metric_options()) :: metric_result()
Writes value
to the set identified by metric_name
.
Examples
iex> Dogmatix.set("my_dogmatix", "metric.set", 42)
:ok
Specs
start_link(id(), binary(), pos_integer(), start_options()) :: Supervisor.on_start()
Starts a new pool of connection to an agent.
name
- a binary or an atom to identify this instance of Dogmatixhost
- a binary, the agent's hostport
- a positive integer, the agent's host
Options
See the module documentation for details.
:worker_count
- (positive integer) - number of UDP sockets and workers used to distribute the metrics. Defaults to4
.:prefix
- (binary) - all metrics sent to the agent will be prefixed with this value. Not set by default.:tags
- ([binary]) - a list of tags to be sent with all metrics. Format:["tag1:value1", "tag2:value2"]
. Not set by default.:max_datagram_size
- (integer) - the maximum number of bytes for a message that can be sent. Defaults to1432
.:buffer_flush_ms
- (integer) - metric flush interval in milliseconds. Defaults to500
.0
to disable.
Specs
timer(id(), binary(), metric_value(), metric_options()) :: metric_result()
Writes value
to the timer identified by metric_name
.
Examples
iex> Dogmatix.timer("my_dogmatix", "query_latency", 15)
:ok