Metrics plugins
Plugins allow using a unified interface to collect metrics without worrying about the way metrics export is performed. If you want to use another DB to store metrics data, you can use an appropriate export plugin just by changing one line of code.
Usage
Import the Prometheus plugin:
local prometheus = require('metrics.plugins.prometheus')
Further, 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>
.
Use in Tarantool http.server as follows:
In Tarantool http.server v1 (currently used in Tarantool Cartridge):
local httpd = require('http.server').new(...) ... httpd:route( { path = '/metrics' }, prometheus.collect_http)
In Tarantool http.server v2 (the latest version):
local httpd = require('http.server').new(...) local router = require('http.router').new(...) httpd:set_router(router) ... router:route( { path = '/metrics' }, prometheus.collect_http)
Sample settings
For Tarantool
http.server
v1:metrics = require('metrics') metrics.enable_default_metrics() 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 (with
http.server
v1):cartridge = require('cartridge') httpd = cartridge.service_get('httpd') metrics = require('metrics') metrics.enable_default_metrics() prometheus = require('metrics.plugins.prometheus') httpd:route( { path = '/metrics' }, prometheus.collect_http)
For Tarantool
http.server
v2:metrics = require('metrics') metrics.enable_default_metrics() prometheus = require('metrics.plugins.prometheus') httpd = require('http.server').new('0.0.0.0', 8080) router = require('http.router').new({charset = "utf8"}) httpd:set_router(router) router:route( { path = '/metrics' }, prometheus.collect_http) httpd:start()
Usage
Import the Graphite plugin:
local graphite = require('metrics.plugins.graphite')
To start automatically exporting the current values of all
metrics.{counter,gauge,histogram}
, just call:
-
metrics.plugins.graphite.
init
(options) Parameters: - options (table) –
Possible options:
prefix
(string) - metrics prefix (default is'tarantool'
);host
(string) - graphite server host (default is'127.0.0.1'
);port
(number) - graphite server port (default is2003
);send_interval
(number) - metrics collect interval in seconds (default is2
);
This creates a background fiber that periodically sends all metrics to a remote Graphite server.
Exported metric name is sent in the format
<prefix>.<metric_name>
.- options (table) –
Usage
Import the JSON 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: Important
Values can be
+-math.huge
,math.huge * 0
. Then:math.inf
is serialized to"inf"
-math.inf
is serialized to"-inf"
nan
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" } ]
To be used in 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
)
We encourage you to use the following methods only when developing a new plugin.
-
metrics.
invoke_callbacks
() Invokes the function registered via
metrics.register_callback(<callback>)
. Used in exporters.
-
metrics.
collectors
() Designed to be used in exporters in favor of
metrics.collect()
.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: - 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: - Concatenation of
-
Inside 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