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.

cd ${PROJECT_ROOT}
tarantoolctl rocks install metrics

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

• Graphite

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

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')

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
}

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.

Registers a new counter. Returns Counter object.

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

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).

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

Registers a new gauge. Returns Gauge object.

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

Same as Counter inc().

Same as inc(), but decreases the observation.

Same as inc(), but sets the observation.

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

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.

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

• num Value to put in histogram (number).

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

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).

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