Metrics plugins | Tarantool
Sign in Sign up
Download

Version:

2.11
Administration Monitoring Metrics plugins

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)
Parameters:
  • 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

Important

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

Note

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
Found what you were looking for?
Feedback
API reference
Grafana dashboard
Single-page version