API reference
An application using the metrics
module has 4 primitives (called «collectors»)
at its disposal:
A collector represents one or more observations that are changing over time.
-
metrics.
counter
(name[, help]) Registers a new counter.
Параметры: Return: Counter object
Rtype: counter_obj
-
object
counter_obj
-
counter_obj:
inc
(num, label_pairs) Increments an observation under
label_pairs
. Iflabel_pairs
didn’t exist before, this creates it.Параметры: - num (number) – Increase value.
- label_pairs (table) – Table containing label names as keys, label values as values.
-
counter_obj:
collect
() Return: Array of observation
objects for the given counter.{ 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
-
-
metrics.
gauge
(name[, help]) Registers a new gauge. Returns a Gauge object.
Параметры: Return: Gauge object
Rtype: gauge_obj
-
object
gauge_obj
-
-
gauge_obj:
inc
(num, label_pairs) Same as
inc()
, but decreases the observation.
-
gauge_obj:
collect
() Returns an array of
observation
objects for the given gauge. Forobservation
description, see counter_obj:collect().
-
-
metrics.
histogram
(name[, help, buckets]) Registers a new histogram.
Параметры: Return: Histogram object
Rtype: histogram_obj
Примечание
The histogram is just a set of collectors:
name .. "_sum"
- A counter holding the sum of added observations. Contains only an empty label set.name .. "_count"
- A counter holding the number of added observations. Contains only an empty label set.name .. "_bucket"
- A counter holding all bucket sizes under the labelle
(low or equal). So to access a specific bucketx
(x
is a number), you should specify the valuex
for the labelle
.
-
metrics.
summary
(name[, help, objectives]) Registers a new summary. Quantile computation is based on the algorithm «Effective computation of biased quantiles over data streams»
Параметры: Return: Summary object
Rtype: summary_obj
Примечание
The summary is just a set of collectors:
name .. "_sum"
- A counter holding the sum of added observations.name .. "_count"
- A counter holding the number of added observations.name
- It’s holding all quantiles under observation under the labelquantile
(low or equal). So to access a specific quantilex
(x
is a number), you should specify the valuex
for the labelquantile
.
All collectors support providing label_pairs
on data modification.
Labels are basically a metainfo that you associate with a metric in the format
of key-value pairs. See tags in Graphite and labels in Prometheus.
Labels are used to differentiate the characteristics of a thing being
measured. For example, in a metric associated with the total number of http
requests, you can use methods and statuses label pairs:
http_requests_total_counter:inc(1, {method = 'POST', status = '200'})
You don’t have to predefine labels in advance.
Using labels on your metrics allows you to later derive new time series (visualize their graphs) by specifying conditions on label values. In the example above, we could derive these time series:
- The total number of requests over time with method = «POST» (and any status).
- The total number of requests over time with status = 500 (and any method).
You can also set global labels by calling
metrics.set_global_labels({ label = value, ...})
.
-
metrics.
enable_default_metrics
() Enables Tarantool metrics collections. See metrics reference for details.
-
metrics.
enable_cartridge_metrics
() Enables Cartridge metrics collections. See metrics reference for details.
-
metrics.
set_global_labels
(label_pairs) Set global labels that will be added to every observation.
Параметры: - label_pairs (table) – Table containing label names as string keys, label values as values (table).
Global labels are applied only on metrics collection and have no effect on how observations are stored.
Global labels can be changed on the fly.
Observation
label_pairs
has priority over global labels: if you passlabel_pairs
to an observation method with the same key as some global label, the method argument value will be used.
metrics
also provides a middleware for monitoring HTTP
(set by the http module)
latency statistics.
-
metrics.http_middleware.
configure_default_collector
(type_name, name, help) Registers a collector for the middleware and sets it as default.
Параметры: If a collector with the same type and name already exists in the registry, throws an error.
-
metrics.http_middleware.
build_default_collector
(type_name, name[, help]) Registers a collector for the middleware and returns it.
Параметры: If a collector with the same type and name already exists in the registry, throws an error.
-
metrics.http_middleware.
set_default_collector
(collector) Sets the default collector.
Параметры: - collector – Middleware collector object.
-
metrics.http_middleware.
get_default_collector
() Returns the default collector. If the default collector hasn’t been set yet, registers it (with default
http_middleware.build_default_collector(...)
parameters) and sets it as default.
-
metrics.http_middleware.
v1
(handler, collector) Latency measure wrap-up for HTTP ver. 1.x.x handler. Returns a wrapped handler.
Параметры: - handler (function) – Handler function.
- collector – Middleware collector object.
If not set, uses the default collector
(like in
http_middleware.get_default_collector()
).
Usage:
httpd:route(route, http_middleware.v1(request_handler, collector))
For a more detailed example, see https://github.com/tarantool/metrics/blob/master/example/HTTP/latency_v1.lua
-
metrics.http_middleware.
v2
(collector) Returns the latency measure middleware for HTTP ver. 2.x.x.
Параметры: - collector – Middleware collector object.
If not set, uses the default collector
(like in
http_middleware.get_default_collector()
).
Usage:
router = require('http.router').new() router:route(route, request_handler) router:use(http_middleware.v2(collector), {name = 'http_instrumentation'}) -- the second argument is optional, see HTTP docs
For a more detailed example, see https://github.com/tarantool/metrics/blob/master/example/HTTP/latency_v2.lua
- collector – Middleware collector object.
If not set, uses the default collector
(like in
CPU metrics work only on Linux. See metrics reference for details. To enable it you should register callback:
local metrics = require('metrics')
metrics.register_callback(function()
local cpu_metrics = require('metrics.psutils.cpu')
cpu_metrics.update()
end)
Collected metrics example
# HELP tnt_cpu_total Host CPU time
# TYPE tnt_cpu_total gauge
tnt_cpu_total 15006759
# HELP tnt_cpu_thread Tarantool thread cpu time
# TYPE tnt_cpu_thread gauge
tnt_cpu_thread{thread_name="coio",file_name="init.lua",thread_pid="699",kind="system"} 160
tnt_cpu_thread{thread_name="tarantool",file_name="init.lua",thread_pid="1",kind="user"} 949
tnt_cpu_thread{thread_name="tarantool",file_name="init.lua",thread_pid="1",kind="system"} 920
tnt_cpu_thread{thread_name="coio",file_name="init.lua",thread_pid="11",kind="user"} 79
tnt_cpu_thread{thread_name="coio",file_name="init.lua",thread_pid="699",kind="user"} 44
tnt_cpu_thread{thread_name="coio",file_name="init.lua",thread_pid="11",kind="system"} 294
Prometheus query aggregated by thread name
sum by (thread_name) (idelta(tnt_cpu_thread[$__interval]))
/ scalar(idelta(tnt_cpu_total[$__interval]) / tnt_cpu_count)
Below are examples of using metrics primitives.
Notice that this usage is independent of export-plugins such as Prometheus / Graphite / etc. For documentation on plugins usage, see their the Metrics plugins section.
Using counters:
local metrics = require('metrics')
-- create a counter
local http_requests_total_counter = metrics.counter('http_requests_total')
-- somewhere in the 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)