erl_optics
An OTP application for optics, a library to produce time series metrics.
Requirements
- Erlang OTP >= 21
- optics v1.1.10
Building
$ rebar3 compile
Usage
For now, erl-optics only supports the carbon backend. This mode requires the following parameters to be added to a config file and loaded:
{erl_optics, [
{hostname, "https://my-carbon-host.com"},
{port, 2003},
{mode, carbon},
{interval, 10000}
]}
To start the application:
erl_optics_app:start(),
To start the optics polling:
erl_optics:start_optics(<<"my_namespace">>),
or
erl_optics:start_optics(<<"my_namespace">>, Lenses),
if some lenses need to be declared before starting the application.
The namespace will be prepending the name of every metric, for
example: "my_namespace.my_counter"
The only lenses that require initial declaration are histo and quantile. If they are unused, they can be omitted, otherwise, they must be declared like so:
Lenses = [erl_optics_lens:histo(<<"histo_name">>, [10, 20, 30, 40]),
erl_optics_lens:quantile(<<"quantile_name">>, 0.50, 10.0, 0.5)],
erl_optics:start_optics(<<"optics_namespace">>, Lenses).
Lenses
counter
A simple counter, polling will give the total increment value. Increment defaults to 1.
erl_optics:counter_inc(<<"my_counter_name">>),
or
erl_optics:counter_inc(<<"my_counter_name">, 10),
gauge
Will keep the last value given to it. As long as no new value has been received, it will keep sending the same.
erl_optics:gauge_set(<<"my_gauge_name">>, 1.0),
dist
Gives an estimation of the distribution of the values given to it. It provides metrics for 50th, 90th and 99th percentiles, the total number of values fed to it and the maximum value.
erl_optics:dist_record(<<"my_dist_name">>, 10.0)
Dist can also be used to record timings with the two variants
dist_record_timing_now
(seconds) and dist_record_timing_now_us
(micro seconds) that
expect erlang timestamps as values and will record the difference
between the moment it is called and the timestamp receives:
Time = os:timestamp(),
% some things happen here
erl_optics:dist_record_timing_now_us(<<"my_dist_name">>, Time),
histo
Histo is a collection of buckets who are incremented every time a value within their boundaries is received. It is necessary to declare these lenses when starting optics:
erl_optics_lens:histo(<<"my_histo_name">>, [0, 10, 20, 30])
To add a value to the histogram:
erl_optics:histo_inc(<<"my_histo_name">>, 11.5),
The bucket list must be an ordered list of different integers that represent the lower and higher boundaries of each buckets. For example, [0, 1, 2, 3] means 3 buckets: [0, 1), [1, 2) and [2, 3).
quantile
Quantile is an estimation of the quantile value for a given percentile (e.g. if the percentile is 0.8, and the quantile is 10.0, that means that ~80% of values were below 10.0). It is necessary to declare these lenses when starting optics.
erl_optics_lens:quantile(<<"my_quantile_name">>, <target_quantile>, <estimated_value>, <adjustment_value>)
- target_quantile: float, wanted percentile.
- estimated_value: expected value for given percentile
- adjustment_value: will affect the speed at which the lens converges to the correct quantile value and the precision. (e.g. an adjustement of 0.1 means that the estimated quantile will rise by 0.1 when it receives a value over itself)
Polling
In the carbon mode, polling will happen periodically at the time interval given in the parameters. When polling occurs, the metrics are sent at the carbon address:port via TCP in a carbon-friendly format.
If the lenses values need to be accessed directly, an erlang poller can be used instead
erl_optics:register_erlang_poller(),
and then the polling can be done via:
erl_optics:poll()
which will return a map containing all the lenses and their values at the moment of polling. Users should be aware that polling at irregular time intervals may affect the merging of some metrics.
Foil parameters
To allow dynamic use of counters, gauges and dists, the erl_optics_foil_server is triggered when they are used and will reload the foil table after the determined foil_reload_interval.
Environment variables
Name | Type | Default | Description |
---|---|---|---|
hostname | string() | "localhost" | Address where the metrics will be sent in carbon mode |
port | non_neg_integer() | 1055 | port where the metrics will be sent in carbon mode |
interval | non_neg_integer() | 10000 | Time (in milliseconds) between polls |
foil_reload_interval | non_neg_integer() | 1000 | Time (in milliseconds) the time a new metric is loaded and the foil table is reloaded |
mode | carbon | blank | blank | Application mode |
foil_namespace | atom() | erl_optics | Namespace used for the foil table |