Metrics plugins

Plugins let you collect metrics through a unified interface without worrying about the way metrics export works. If you want to use another DB to store metrics data, you can enable an appropriate export plugin just by changing one line of code.

Available plugins

Prometheus

Usage

Import the plugin:

local prometheus = require('metrics.plugins.prometheus')

Then use the prometheus.collect_http() function, which returns:

{
    status = 200,
    headers = <headers>,
    body = <body>,
}

See the Prometheus exposition format for details on <body> and <headers>.

With Tarantool http.server, use this plugin as follows:

local httpd = require('http.server').new(...)
...
httpd:route( { path = '/metrics' }, prometheus.collect_http)

Sample settings

For Tarantool:

metrics = require('metrics')
metrics.cfg{}
prometheus = require('metrics.plugins.prometheus')
httpd = require('http.server').new('0.0.0.0', 8080)
httpd:route( { path = '/metrics' }, prometheus.collect_http)
httpd:start()

For Tarantool Cartridge:

cartridge = require('cartridge')
httpd = cartridge.service_get('httpd')
metrics = require('metrics')
metrics.cfg{}
prometheus = require('metrics.plugins.prometheus')
httpd:route( { path = '/metrics' }, prometheus.collect_http)

Graphite

Usage

Import the plugin:

local graphite = require('metrics.plugins.graphite')

To start automatically exporting the current values of all metrics.{counter,gauge,histogram}, call the following function:

metrics.plugins.graphite.init(options)¶

Параметры:	options (`table`) – possible options: `prefix` (string): metrics prefix (`'tarantool'` by default) `host` (string): Graphite server host (`'127.0.0.1'` by default) `port` (number): Graphite server port (`2003` by default) `send_interval` (number): metrics collection interval in seconds (`2` by default)

This function creates a background fiber that periodically sends all metrics to a remote Graphite server.

Exported metric names are formatted as follows: <prefix>.<metric_name>.

JSON

Usage

Import the plugin:

local json_metrics = require('metrics.plugins.json')

metrics.plugins.json.export()¶

Return:	the following structure [ { "name": "<name>", "label_pairs": { "<name>": "<value>", "...": "..." }, "timestamp": "<number>", "value": "<value>" }, "..." ]
Rtype:	string

Важно

The values can also be +-math.huge and math.huge * 0. In such case:

math.huge is serialized to "inf"
-math.huge is serialized to "-inf"
math.huge * 0 is serialized to "nan".

Example

[
    {
        "label_pairs": {
            "type": "nan"
        },
        "timestamp": 1559211080514607,
        "metric_name": "test_nan",
        "value": "nan"
    },
    {
        "label_pairs": {
            "type": "-inf"
        },
        "timestamp": 1559211080514607,
        "metric_name": "test_inf",
        "value": "-inf"
    },
    {
        "label_pairs": {
            "type": "inf"
        },
        "timestamp": 1559211080514607,
        "metric_name": "test_inf",
        "value": "inf"
    }
]

Use the JSON plugin with Tarantool http.server as follows:

local httpd = require('http.server').new(...)
...
httpd:route({
        method = 'GET',
        path = '/metrics',
        public = true,
    },
    function(req)
        return req:render({
            text = json_exporter.export()
        })
    end
)

Plugin-specific API

Use the following methods only when developing a new plugin.

metrics.invoke_callbacks()¶: Invoke a function registered via metrics.register_callback(<callback>). Used in exporters.

metrics.collectors()¶

List all collectors in the registry. Designed to be used in exporters.

Return:	A list of created collectors.

object collector_object¶

collector_object:collect()¶

Примечание

You’ll probably want to use metrics.collectors() instead.

Equivalent to:

for _, c in pairs(metrics.collectors()) do
    for _, obs in ipairs(c:collect()) do
        ...  -- handle observation
    end
end

Return:	A concatenation of `observation` objects across all created collectors. { 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 }
Rtype:	table

Creating custom plugins

Include the following in your main export function:

-- Invoke all callbacks registered via `metrics.register_callback(<callback-function>)`
metrics.invoke_callbacks()

-- Loop over collectors
for _, c in pairs(metrics.collectors()) do
    ...

    -- Loop over instant observations in the collector
    for _, obs in pairs(c:collect()) do
        -- Export observation `obs`
        ...
    end

end

Версия:

Metrics plugins

Available plugins

Prometheus

Usage

Sample settings

Graphite

Usage

JSON

Usage

Plugin-specific API

Creating custom plugins