Getting started with Cartridge application

Module setup

First, install the latest version of metrics. For details, check the installation guide.

Also, you need to install the separate cartridge-metrics-role rock. To do this:

1. Add the cartridge-metrics-role package to the dependencies in the .rockspec file:

   dependencies = {
       ...
       'cartridge-metrics-role',
       ...
   }
   

2. Next, install the missing dependencies:

   tt rocks make
   # OR #
   cartridge build
   

After the cartridge-metrics-role installation, enable this package in the list of roles in cartridge.cfg:

local ok, err = cartridge.cfg({
    roles = {
        ...
        'cartridge.roles.metrics',
        ...
    },
})

Then, configure the metrics module in either of two ways:

• add the metrics configuration section to your cluster configuration;
• specify the configuration in the separate metrics.yml file.

In the configuration, specify the response format and the addresses at which the commands are available:

metrics:
  export:
    - path: '/path_for_json_metrics'
      format: 'json'
    - path: '/path_for_prometheus_metrics'
      format: 'prometheus'
    - path: '/health'
      format: 'health'

Learn more about Cartridge configuration.

Now the commands’ data is accessible at the following addresses:

http://url:port/path_for_json_metrics
http://url:port/path_for_prometheus_metrics
http://url:port/health

where url:port – the address and Cartridge HTTP port of a specific instance of the application.

You can visualize the data in Grafana dashboard.

After the role has been initialized, the default metrics are enabled and the global alias label is set.

You can use the functionality of any metrics package. To do this, get the package as a Cartridge service and call it with the require() like a regular package:

local cartridge = require('cartridge')
local metrics = cartridge.service_get('metrics')

Additional steps for older versions of the metrics module

Since version 0.6.0, the metrics role is permanent and enabled on instances by default. If you use an old version of metrics, you need to enable the role in the interface first:

Adding metrics to HTTP API commands of the application

You can connect the standard http_server_request_latency metric to your application’s HTTP API commands. This metric records the number of invocations and the total execution time (latency) of each individual command. To connect this, wrap each API handler with the metrics.http_middleware.v1(...) function.

Example:

local cartridge = require('cartridge')
local server = cartridge.service_get('httpd') -- get the HTTP server module
local metrics = cartridge.service_get('metrics') -- get the module of metrics

local function http_app_api_handler(request) -- add test command
    return request:render({ text = 'Hello world!!!' })
end

local server = http_server.new('0.0.0.0', 8081)
server:route({path = '/hello'}, metrics.http_middleware.v1(http_app_api_handler))
server:start()

When calling the cartridge.service_get('metrics') command as an application (usually in a router), add a dependency of this role on the role of metrics:

return {
    ...
    dependencies = {
        ...
        'cartridge.roles.metrics',
    }
}

Now after the HTTP API calls hello at http://url:port/path_for_json_metrics, new data on these calls is available:

{
    "label_pairs": {
        "path": "/hello",
        "method": "ANY",
        "status": 200,
        "alias": "my-tnt-app"
    },
    "timestamp": 1679668258972227,
    "metric_name": "http_server_request_latency_count",
    "value": 9
},
{
    "label_pairs": {
        "path": "/hello",
        "method": "ANY",
        "status": 200,
        "alias": "my-tnt-app"
    },
    "timestamp": 1679668258972227,
    "metric_name": "http_server_request_latency_sum",
    "value": 0.00008015199273359
},

The default type for this metric is histogram. However, it’s recommended to use the summary type instead.

Additional settings

• 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 the zone label.

• 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 in init.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.

Creating a custom health check format

By default, the response of the health command contains a status code of

• 200 – if everything is okay,
• 500 – if the instance is unhealthy.

You can set your own response format in the following way:

local health = require('cartridge.health')
local metrics = cartridge.service_get('metrics')

metrics.set_health_handler(function(req)
    local resp = req:render{
        json = {
            my_healthcheck_format = health.is_healthy()
        }
    }
    resp.status = 200
    return resp
end)