Metrics

Metrics is a tool to collect and manipulate metrics time series. Metrics uses a collection of primitives borrowed from the Prometheus TSDB, which can be exported to any TSDB.

Contents:

Installation
Plugins export
Examples
Next steps
Cartridge role
Contribution
Credits

Installation

cd ${PROJECT_ROOT}
tarantoolctl rocks install metrics

Plugins export

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

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

Examples

Below are examples of using metrics primitives.

Note that this usage is independent of export-plugins such as Prometheus / Graphite / etc. For documentation on plugins usage, see this.

Using counters:

local metrics = require('metrics')

-- create a counter
local http_requests_total_counter = metrics.counter('http_requests_total')

-- somewhere in HTTP requests middleware:
http_requests_total_counter:inc(1, {method = 'GET'})

Using gauges:

local metrics = require('metrics')

-- create a gauge
local cpu_usage_gauge = metrics.gauge('cpu_usage', 'CPU usage')

-- register a lazy gauge value update
-- this will be called whenever the export is invoked in any plugins
metrics.register_callback(function()
    local current_cpu_usage = math.random()
    cpu_usage_gauge:set(current_cpu_usage, {app = 'tarantool'})
end)

Using histograms:

local metrics = require('metrics')

-- create a histogram
local http_requests_latency_hist = metrics.histogram(
    'http_requests_latency', 'HTTP requests total', {2, 4, 6})

-- somewhere in the HTTP requests middleware:
local latency = math.random(1, 10)
http_requests_latency_hist:observe(latency)

Using summaries:

local metrics = require('metrics')

-- create a summary
local http_requests_latency = metrics.summary(
    'http_requests_latency', 'HTTP requests total',
    {[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}
)

-- somewhere in the HTTP requests middleware:
local latency = math.random(1, 10)
http_requests_latency:observe(latency)

Cartridge role

cartridge.roles.metrics is a role for tarantool/cartridge. It allows to use default metrics in a Cartridge application and manage them via configuration.

Usage

Add the metrics package to dependencies in the .rockspec file. Make sure that you are using version 0.3.0 or higher.
```
dependencies = {
    ...
    'metrics >= 0.3.0-1',
    ...
}
```

Add cartridge.roles.metrics to the roles list in cartridge.cfg in your entry-point file (e.g. init.lua).

local ok, err = cartridge.cfg({
    ...
    roles = {
        ...
        'cartridge.roles.metrics',
        ...
    },
})

After role initialization, default metrics will be enabled and the global label 'alias' will be set. If you need to use the functionality of any metrics package, you may get it as a Cartridge service and use it like a regular package after require:
```
local cartridge = require('cartridge')
local metrics = cartridge.service_get('metrics')
```

To view metrics via API endpoints, use the following configuration (to learn more about Cartridge configuration, see this):

metrics:
  export:
    - path: '/path_for_json_metrics'
      format: 'json'
    - path: '/path_for_prometheus_metrics'
      format: 'prometheus'

You can add several entry points of the same format by different paths, like this:

metrics:
  export:
    - path: '/path_for_json_metrics'
      format: 'json'
    - path: '/another_path_for_json_metrics'
      format: 'json'

Next steps

See:

A more detailed getting started guide
Metrics API reference
Detailed information on plugins

Contribution

Feel free to send Pull Requests. For example, you can support new time series aggregation / manipulation functions (but be sure to check if there are any Prometheus analogues to borrow API from).

Credits

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

DifferentialOrange/metrics