Metrics

Metrics is a tool to collect, store and manipulate metrics timeseriess.
Metrics uses a collection of primitives borrowed from Prometheus TSDB, which can be exported to any TSDB or can be used to build complex metrics with server-side aggregation and filtering.

Installation

cd ${PROJECT_ROOT}
tarantoolctl rocks install metrics

Export Plugins

In order to easily export metrics to any TSDB you can use one of supported export plugins:

or you can write your custom plugin and use it. Hopefully, plugins for other TSDBs will be supported soon.

API

Collectors

The application using metrics module has 3 primitives (called collectors) at its disposal:

Counter
Gauge
Histogram

Collectors represent an observation or a few that are changing over time.

Counter and Gauge collectors support labels, which are essentially a key-value pairs.
Labels allow collectors to store a separate observation per each label set added.
New label sets are added automatically when collector invokes modification function with this label set specified for the first time.

-- importing metrics
metrics = require('metrics')

`metrics.enable_default_metrics()`

Enables default metrics collections. Collects tarantool metrics, ported from https://github.com/tarantool/stat

`metrics.collectors()`

Returns a list of created collectors. Designed to be used in exporters in favor of metrics.collect().

`metrics.collect()`

**NOTE**: You'll probably want to use `metrics.collectors()` instead.
Equivalent to:
```lua
for _, c in pairs(metrics.collectors()) do_
    for _, obs in ipairs(c:collect()) do
        ...  -- handle observation
    end_
end
```

Returns concatenation of observation objects across all collectors created.

observation is a Lua table:

{
  label_pairs: table,          -- `label_pairs` key-value table
  timestamp: ctype<uint64_t>,  -- current system time (in microseconds)
  value: number,               -- current value
  metric_name: string,         -- collector
}

`client_obj.register_callback(callback)`

Registers a function callback which will be called before collecting observations every time when metrics.collect() called.

callback Function which takes no parameters.

It may be used for calculation some metric right before collecting.

`metrics.invoke_callbacks()`

Invokes function registered via metrics.register_callback(<callback>) Used in exporters.

Creating and Using Collectors

Counter

`metrics.counter(name, help)`

Registers a new counter. Returns Counter object.

name Collector name (string). Must be unique.
help Help description (string). Currently it's just ignored.

`counter_obj:inc(num, label_pairs)`

Increments observation under label_pairs. If label_pairs didn't exist before - this creates it.

num Increase value (number).
label_pairs Table containing label names as keys, label values as values (table).

`counter_obj:collect()`

Returns array of observation objects for given counter.
For observation description see metrics.collect() section.

Gauge

`metrics.gauge(name, help)`

Registers a new gauge. Returns Gauge object.

name Collector name (string). Must be unique.
help Help description (string). Currently it's just ignored.

`gauge_obj:inc(num, label_pairs)`

Same as Counter inc().

`gauge_obj:dec(num, label_pairs)`

Same as inc(), but decreases the observation.

`gauge_obj:set(num, label_pairs)`

Same as inc(), but sets the observation.

`gauge_obj:collect()`

Returns array of observation objects for given gauge.
For observation description see metrics.collect() section.

Histogram

`client_obj.histogram(name, help, buckets)`

Registers a new histogram. Returns Histogram object.

name Collector name (string). Must be unique.
help Help description (string). Currently it's just ignored.
buckets Histogram buckets (array of positive sorted numbers). INF bucket is added automatically. Default is {.005, .01, .025, .05, .075, .1, .25, .5, .75, 1.0, 2.5, 5.0, 7.5, 10.0, INF}.

NOTE: The histogram is just a set of collectors:

name .. "_sum" - Counter holding sum of added observations. Has only empty labelset.
name .. "_count" - Counter holding number of added observations. Has only empty labelset.
name .. "_bucket" - Counter holding all bucket sizes under label le (low or equal). So to access specific bucket x (x is a number), you should specify value x for label le.

`histogram_obj:observe(num, label_pairs)`

Records a new value in histogram. This increments all buckets sizes under labels le >= num and labels matching label_pairs.

num Value to put in histogram (number).
label_pairs Table containing label names as keys, label values as values (table). New value is observed by all internal counters with these labels specified

`histogram_obj:collect()`

Returns concatenation of counter_obj:collect() across all internal counters of histogram_obj.
See above counter_obj:collect() for details.

CONTRIBUTION

Feel free to send Pull Requests. E.g. you can support new timeseriess aggregation / manipulation functions (but be sure to check if there are any Prometheus analogues to borrow API from).

CREDIT

We would like to thank Prometheus for a great API that we brusquely borrowed.

Kasen / metrics