Monitoring: getting started
First, install the metrics
package:
$ cd ${PROJECT_ROOT}
$ tarantoolctl rocks install metrics
Next, require it in your code:
local metrics = require('metrics')
Enable default Tarantool metrics such as network, memory, operations, etc. You may also set a global label for your metrics:
metrics.cfg{alias = 'alias'}
Initialize the Prometheus exporter or export metrics in another format:
local httpd = require('http.server')
local http_handler = require('metrics.plugins.prometheus').collect_http
httpd.new('0.0.0.0', 8088)
:route({path = '/metrics'}, function(...)
return http_handler(...)
end)
:start()
box.cfg{
listen = 3302
}
Now you can use the HTTP API endpoint /metrics
to collect your metrics
in the Prometheus format. To learn how to obtain custom metrics, check the
API reference.
To enable the collection of HTTP metrics, you need to create a collector first.
local httpd = require('http.server').new(ip, port)
-- Create a summary collector for latency
local collector = metrics.http_middleware.build_default_collector('summary')
-- Set a route handler for latency summary collection
httpd:route({ path = '/path-1', method = 'POST' }, metrics.http_middleware.v1(handler_1, collector))
httpd:route({ path = '/path-2', method = 'GET' }, metrics.http_middleware.v1(handler_2, collector))
-- Start HTTP routing
httpd:start()
You can collect all HTTP metrics with a single collector. If you’re using the default Grafana dashboard, don’t change the default collector name. Otherwise, your metrics won’t appear on the charts.
In production environments, Tarantool Cartridge usually has a large number of so-called routers – Tarantool instances that handle input load. Various load balancers help distribute that load evenly. However, any load balancer has to know which routers are ready to accept the load at the moment. The Tarantool metrics library has a special plugin that creates an HTTP handler, which the load balancer can use to check the current state of any Tarantool instance. If the instance is ready to accept the load, it will return a response with a 200 status code, and if not, with a 500 status code.
cartridge.roles.metrics
is a
Tarantool Cartridge role.
It allows using default metrics in a Cartridge application and managing them
via Cartridge configuration.
Usage
Add
cartridge-metrics-role
package to the dependencies in the.rockspec
file.dependencies = { ... 'cartridge-metrics-role >= 0.1.0-1', ... }
If you’re using older version of metrics package, you need to add
metrics
package instead ofcartridge-metrics-role
.dependencies = { ... 'metrics == 0.17.0-1', ... }
Cartridge role is present in package versions from 0.3.0 to 0.17.0.
Make sure that
cartridge.roles.metrics
is included in the roles list incartridge.cfg
in your entry point file (for example,init.lua
):local ok, err = cartridge.cfg({ ... roles = { ... 'cartridge.roles.metrics', ... }, })
To get metrics via API endpoints, use
set_export
.Примечание
set_export
has lower priority than clusterwide configuration and may be overridden by the metrics configuration.local metrics = require('cartridge.roles.metrics') metrics.set_export({ { path = '/path_for_json_metrics', format = 'json' }, { path = '/path_for_prometheus_metrics', format = 'prometheus' }, { path = '/health', format = 'health' } })
You can add several endpoints of the same format with different paths. For example:
metrics.set_export({ { path = '/path_for_json_metrics', format = 'json' }, { path = '/another_path_for_json_metrics', format = 'json' }, })
The metrics will be available on the path specified in
path
, in the format specified informat
.Since version 0.6.0, the metrics role is permanent and enabled on instances by default. If you use old version of metrics, you should enable the role in the interface:
After the role has been initialized, the default metrics will be enabled and the global label
alias
will be set. Note that thealias
label value is set by thealias
orinstance_name
instance configuration option (since 0.6.1).You can use the functionality of any metrics package by getting it as a Cartridge service and calling it with
require
like a regular package:local cartridge = require('cartridge') local metrics = cartridge.service_get('metrics')
Since Tarantool Cartridge
2.4.0
, you can set a zone for each instance in the cluster. When a zone is set, all the metrics on the instance receive thezone
label.To change the HTTP path for a metric in runtime, you can use the configuration below. Learn more about Cartridge configuration). It is not recommended to set up the metrics role in this way. Use
set_export
instead.metrics: export: - path: '/path_for_json_metrics' format: 'json' - path: '/path_for_prometheus_metrics' format: 'prometheus' - path: '/health' format: 'health'
You can set custom global labels with the following configuration:
metrics: export: - path: '/metrics' format: 'json' global-labels: my-custom-label: label-value
Another option is to invoke the
set_default_labels
function ininit.lua
:local metrics = require('cartridge.roles.metrics') metrics.set_default_labels({ ['my-custom-label'] = 'label-value' })
You can use the configuration below to choose the default metrics to be exported. If you add the include section, only the metrics from this section will be exported:
metrics: export: - path: '/metrics' format: 'json' # export only vinyl, luajit and memory metrics: include: - vinyl - luajit - memory
If you add the exclude section, the metrics from this section will be removed from the default metrics list:
metrics: export: - path: '/metrics' format: 'json' # export all metrics except vinyl, luajit and memory: exclude: - vinyl - luajit - memory
For the full list of default metrics, check the API reference.