Модуль metrics

Начиная с: 2.11.1

Модуль metrics предоставляет возможность собирать и предоставлять метрики Tarantool.

В Tarantool доступны следующие коллекторы метрик:

Коллектор представляет собой одно или несколько наблюдений, изменяющихся во времени.

Счетчик — это кумулятивная метрика, обозначающая единый монотонно возрастающий счетчик. Его значение может только увеличиваться или быть сброшено в ноль при перезапуске. Например, счетчик можно использовать для представления количества обработанных запросов, выполненных задач или ошибок.

Реализация основана на счетчике Prometheus.

Gauge — это метрика, обозначающая одно числовое значение, которое может произвольно увеличиваться и уменьшаться.

Тип gauge обычно используется для измеряемых значений, таких как температура или текущее использование памяти. Он также может применяться для значений, которые могут увеличиваться или уменьшаться, например, для количества одновременных запросов.

В основе дизайна лежит gauge в Prometheus.

Метрика типа «гистограмма» используется для сбора и анализа статистических данных о распределении значений в приложении. В отличие от метрик, отслеживающих среднее значение или количество событий, гистограмма дает подробное представление о распределении значений, что позволяет выявить скрытые зависимости.

В основе реализации лежит гистограмма Prometheus.

Метрика типа summary используется для сбора статистических данных о распределении значений в приложении.

Каждая метрика типа summary предоставляет несколько измерений:

• общее количество измерений
• сумма измеренных значений
• значения для конкретных квантилей

Как и гистограммы, метрика типа summary также работает с диапазонами значений. Однако, в отличие от гистограмм, для этого используются квантили (определяемые числом от 0 до 1). В данном случае задавать фиксированные границы не требуется. Для метрики типа summary диапазоны зависят от измеряемых значений и количества измерений.

Дизайн основан на summary в Prometheus.

Метка — это элемент метаданных, связываемый с метрикой в формате «ключ-значение». Подробнее см. метки в Prometheus и теги в Graphite.

Метки используются для разделения характеристик измеряемого объекта. Например, в метрике, связанной с общим количеством HTTP-запросов, можно представить методы и статусы в виде пар меток:

 
http_requests_total_counter:inc(1, { method = 'POST', status = '200' })

Из приведенного выше примера можно извлечь следующие временные ряды:

1. Общее количество запросов с течением времени с method = "POST" (и любым статусом).
2. Общее количество запросов с течением времени с status = 500 (и любым методом).

Для настройки метрик используйте metrics.cfg(). Эту функцию можно использовать для включения или выключения указанных метрик, а также для настройки меток, применяемых ко всем сборщикам. Кроме того, для настройки метрик или меток можно использовать следующие вспомогательные функции:

• metrics.enable_default_metrics()
• metrics.set_global_labels()

Чтобы создать пользовательскую метрику, выполните следующие шаги:

1. Создание метрики

   Чтобы создать новую метрику, вызовите функцию, соответствующую нужному типу коллектора. Например, вызовите metrics.counter() или metrics.gauge() для создания нового счетчика или измерителя соответственно. В примере ниже создается новый счетчик:

    
   local metrics = require('metrics')local bands_replace_count = metrics.counter('bands_replace_count', 'The number of data operations')

   Этот счетчик предназначен для сбора количества операций с данными, выполненных над указанным спейсом.

   В следующем примере создается измеритель:

    
   local metrics = require('metrics')local bands_waste_size = metrics.gauge('bands_waste_size', 'The size of memory wasted due to internal fragmentation')

2. Отслеживание значения

   Отслеживать значение можно двумя способами:

   • В нужном месте, например, в обработчике API-запроса или триггере. В примере ниже значение счетчика увеличивается каждый раз при выполнении операции с данными в спейсе bands. Для увеличения значения счетчика вызывается counter_obj:inc().

   • В момент запроса данных, собранных метриками. В этом случае нужно собрать нужную метрику внутри metrics.register_callback(). В примере ниже показано, как использовать коллектор типа gauge для измерения объема памяти, теряемой из-за внутренней фрагментации:

     Для установки значения измерителя вызывается gauge_obj:set().

Полный пример доступен на GitHub: metrics_collect_custom.

С помощью модуля можно добавлять собственные метрики, однако при работе с определенными инструментами есть некоторые нюансы.

При добавлении пользовательской метрики важно следить за тем, чтобы количество комбинаций значений меток было минимальным. В противном случае в базе данных временных рядов, где хранятся значения метрик, может произойти комбинаторный взрыв. Примеры меток данных:

• Метки (Labels) в Prometheus
• Теги (Tags) в InfluxDB

Например, если в вашей компании для сбора метрик используется InfluxDB, можно нарушить всю конфигурацию мониторинга — как для вашего приложения, так и для всех остальных систем компании. В результате данные мониторинга, скорее всего, будут потеряны.

Пример:

 
local some_metric = metrics.counter('some', 'Some metric')-- THIS IS POSSIBLElocal function on_value_update(instance_alias)   some_metric:inc(1, { alias = instance_alias })end-- THIS IS NOT ALLOWEDlocal function on_value_update(customer_id)   some_metric:inc(1, { customer_id = customer_id })end

В примере показаны две версии функции on_value_update. Верхняя версия помечает данные псевдонимом экземпляра в кластере. Поскольку количество узлов относительно невелико, использование их в качестве меток допустимо. Во втором случае используется идентификатор записи. Если записей много, рекомендуется избегать подобных ситуаций.

Тот же принцип применим к URL. Не рекомендуется использовать полный URL с параметрами. Вместо этого используйте шаблон URL или имя команды.

По сути, при проектировании пользовательских метрик и выборе меток или тегов важно выбирать минимальный набор значений, который однозначно идентифицирует данные, не создавая лишней сложности или потенциальных конфликтов с существующими метриками и системами.

Модуль metrics предоставляет промежуточное ПО для мониторинга статистики задержек HTTP для конечных точек, созданных с помощью модуля http. Сборщик метрик задержек отслеживает как информацию о задержках, так и количество вызовов. Метрики, собранные промежуточным ПО HTTP, разделяются набором меток:

• маршрут (path)
• метод (method)
• код состояния HTTP (status)

Для каждого маршрута, который нужно отслеживать, необходимо явно указать промежуточное ПО. В приведенном ниже примере показано, как собирать статистику для запросов, отправляемых на конечную точку /metrics/hello.

 
httpd = require('http.server').new('127.0.0.1', 8080)local metrics = require('metrics')metrics.http_middleware.configure_default_collector('summary')httpd:route({    method = 'GET',    path = '/metrics/hello'}, metrics.http_middleware.v1(        function()            return { status = 200,                     headers = { ['content-type'] = 'text/plain' },                     body = 'Hello from http_middleware!' }        end))httpd:start()

Модуль metrics предоставляет набор плагинов для сбора метрик через единый интерфейс:

• metrics-prometheus-api_reference
• metrics-json-api_reference
• metrics-graphite-api_reference

Например, чтобы получить объект HTTP-ответа, содержащий метрики в формате Prometheus, вызовите функцию metrics.plugins.prometheus.collect_http():

 
local prometheus_plugin = require('metrics.plugins.prometheus')local prometheus_metrics = prometheus_plugin.collect_http()

Чтобы опубликовать собранные метрики, можно использовать модуль http:

 
httpd = require('http.server').new('127.0.0.1', 8080)httpd:route({    method = 'GET',    path = '/metrics/prometheus'}, function()    local prometheus_plugin = require('metrics.plugins.prometheus')    local prometheus_metrics = prometheus_plugin.collect_http()    return prometheus_metricsend)httpd:start()

Пример на GitHub: metrics_plugins

Для создания пользовательских плагинов используйте следующий API:

• metrics.invoke_callbacks()
• metrics.collectors()
• collector_object

Для создания плагина в основной функции экспорта необходимо включить следующее:

 
-- Invoke all callbacks registered via `metrics.register_callback(<callback-function>)`metrics.invoke_callbacks()-- Loop over collectorsfor _, c in pairs(metrics.collectors()) do    ...    -- Loop over instant observations in the collector    for _, obs in pairs(c:collect()) do        -- Export observation `obs`        ...    endend

Исходный код встроенных плагинов доступен в репозитории metrics на GitHub.

Точка входа для настройки модуля.

Параметры:

• config (table) — параметры конфигурации модуля:

  • cfg.include (строка/таблица, по умолчанию all): all для включения всех поддерживаемых метрик по умолчанию, none для отключения всех метрик по умолчанию, таблица с именами метрик по умолчанию для включения определенного набора метрик.
  • cfg.exclude (таблица, по умолчанию {}): таблица, содержащая имена метрик по умолчанию, которые требуется отключить. Имеет более высокий приоритет, чем cfg.include.
  • cfg.labels (таблица, по умолчанию {}): таблица, содержащая имена меток в качестве строковых ключей и значения меток в качестве значений. См. также: метки.

К metrics.cfg можно обращаться как к таблице для чтения значений, но для их обновления необходимо вызывать metrics.cfg{} как функцию.

Поддерживаемые имена метрик по умолчанию (для таблиц cfg.include и cfg.exclude):

• all (метасекция, включающая все метрики)
• network
• operations
• system
• replicas
• info
• slab
• runtime
• memory
• spaces
• fibers
• cpu
• vinyl
• memtx
• luajit
• clock
• event_loop
• config

Подробнее см. справочник по метрикам. Все коллекторы метрик из коллекции имеют metainfo.default = true.

cfg.labels — глобальные метки, добавляемые к каждому наблюдению.

Глобальные метки применяются только при сборе метрик. Они не влияют на способ хранения наблюдений.

Глобальные метки можно изменять на лету.

label_pairs из объектов наблюдений имеют приоритет над глобальными метками. Если передать label_pairs в метод наблюдения с тем же ключом, что и у некоторой глобальной метки, будет использовано значение аргумента метода.

Обратите внимание, что и имена, и значения меток в label_pairs обрабатываются как строки.

Сбор наблюдений из каждого коллектора.

Параметры:

• opts (table) — таблица параметров сбора:

  • invoke_callbacks — если true, invoke_callbacks() вызывается перед фактическим сбором.
  • default_only — если true, наблюдения содержат только метрики по умолчанию (metainfo.default = true).

Выводит список всех коллекторов в реестре. Предназначен для использования в экспортерах.

Возвращает

Список созданных коллекторов (см. collector_object).

См. также: создание пользовательских плагинов

Регистрация нового счетчика.

Параметры:

• name (string) — имя коллектора. Должно быть уникальным.
• help (string) — описание коллектора.
• metainfo (table) — метаданные коллектора.

Возвращает

Объект счетчика (см. counter_obj).

Тип возвращаемого значения

counter_obj

См. также: создание пользовательских метрик

Аналогично metrics.cfg{include=include, exclude=exclude}, но include={} обрабатывается как include='all' для обратной совместимости.

Регистрация нового измерителя.

Параметры:

• name (string) — имя коллектора. Должно быть уникальным.
• help (string) — описание коллектора.
• metainfo (table) — метаданные коллектора.

Возвращает

Объект измерителя (см. gauge_obj).

Тип возвращаемого значения

gauge_obj

См. также: создание пользовательских метрик

Регистрация новой гистограммы.

Параметры:

• name (string) — имя коллектора. Должно быть уникальным.
• help (string) — описание коллектора.
• buckets (table) — корзины гистограммы (массив отсортированных положительных чисел). Корзина бесконечности (INF) добавляется автоматически. По умолчанию: {.005, .01, .025, .05, .075, .1, .25, .5, .75, 1.0, 2.5, 5.0, 7.5, 10.0, INF}.
• metainfo (table) — метаданные коллектора.

Возвращает

Объект гистограммы (см. histogram_obj).

Тип возвращаемого значения

histogram_obj

См. также: создание пользовательских метрик

Вызывает все зарегистрированные обратные вызовы. Должен вызываться перед каждым collect(). Также можно использовать collect{invoke_callbacks = true} вместо этого. При использовании одного из стандартных экспортеров invoke_callbacks() будет вызван экспортером.

См. также: создание пользовательских плагинов

Регистрирует функцию с именем callback, которая будет вызвана непосредственно перед сбором метрик при экспорте через плагин.

Параметры:

• callback (function) — функция, не принимающая параметров.

Этот метод чаще всего используется для обновления метрик типа gauge.

Пример:

См. также: пользовательские метрики

Аналогично metrics.cfg{ labels = label_pairs }. Подробнее см. metrics.cfg().

Регистрация новой сводки. Вычисление квантилей основано на алгоритме "Effective computation of biased quantiles over data streams".

Параметры:

• name (string) — имя коллектора. Должно быть уникальным.
• help (string) — описание коллектора.
• objectives (table) — список «целевых» φ-квантилей в формате {quantile = error, ... }. Пример: {[0.5]=0.01, [0.9]=0.01, [0.99]=0.01}. Целевой φ-квантиль задается в виде φ-квантиля и допустимой погрешности. Например, {[0.5] = 0.1} означает, что медиана (= 50-й перцентиль) возвращается с погрешностью 10 процентов. Обратите внимание, что перцентили и квантили — это одно и то же понятие, но перцентили выражаются в процентах. φ-квантиль должен находиться в интервале [0, 1]. Меньшая допустимая погрешность для φ-квантиля приводит к более высокому потреблению памяти и CPU при вычислении сводки.
• params (table) — таблица параметров сводки, используемых для настройки скользящего временного окна. Это окно состоит из нескольких корзин для хранения наблюдений. Новые наблюдения добавляются в каждую корзину. По истечении периода времени головная корзина (из которой собираются наблюдения) сбрасывается, а следующая корзина становится новой головной. Таким образом, каждая корзина хранит наблюдения в течение max_age_time * age_buckets_count секунд до сброса. max_age_time задает продолжительность жизни каждой корзины — то есть, сколько секунд наблюдения хранятся перед удалением. age_buckets_count задает количество корзин в скользящем временном окне. Эта переменная определяет количество корзин, используемых для исключения из сводки наблюдений старше max_age_time. Значение представляет собой компромисс между ресурсами (память и CPU для поддержки корзины) и плавностью перемещения временного окна. Значение по умолчанию: {max_age_time = math.huge, age_buckets_count = 1}.
• metainfo (table) — метаданные коллектора.

Возвращает

Объект сводки (см. summary_obj).

Тип возвращаемого значения

summary_obj

См. также: создание пользовательских метрик

Отменяет регистрацию функции с именем callback, которая вызывается непосредственно перед сбором метрик при экспорте через плагин.

Параметры:

• callback (function) — функция, не принимающая параметров.

Пример:

 
local cpu_callback = function()    local cpu_metrics = require('metrics.psutils.cpu')    cpu_metrics.update()endmetrics.register_callback(cpu_callback)-- after a while, we don't need that callback function anymoremetrics.unregister_callback(cpu_callback)

Регистрирует и возвращает коллектор для промежуточного слоя.

Параметры:

• type_name (string) — тип коллектора: histogram или summary. По умолчанию — histogram.
• name (string) — имя коллектора. По умолчанию — http_server_request_latency.
• help (string) — описание коллектора. По умолчанию — HTTP Server Request Latency.

Возвращает

Объект коллектора

Возможные ошибки:

• Коллектор с таким же типом и именем уже существует в реестре.

Регистрирует коллектор для промежуточного слоя и устанавливает его в качестве коллектора по умолчанию.

Параметры:

• type_name (string) — тип коллектора: histogram или summary. По умолчанию — histogram.
• name (string) — имя коллектора. По умолчанию — http_server_request_latency.
• help (string) — описание коллектора. По умолчанию — HTTP Server Request Latency.

Возможные ошибки:

• Коллектор с таким же типом и именем уже существует в реестре.

Возвращает коллектор по умолчанию. Если коллектор по умолчанию еще не задан, регистрирует его (с параметрами http_middleware.build_default_collector() по умолчанию) и устанавливает в качестве коллектора по умолчанию.

Возвращает

Объект коллектора

Устанавливает коллектор по умолчанию.

Параметры:

• collector — объект коллектора промежуточного слоя

Обертка для измерения задержки обработчика HTTP версии 1.x.x. Возвращает обернутый обработчик.

Подробнее см. сбор HTTP-метрик.

Параметры:

• handler (function) — функция-обработчик.
• collector — объект коллектора промежуточного слоя. Если не задан, используется коллектор по умолчанию (как в http_middleware.get_default_collector()).

Использование:

 
httpd:route(route, http_middleware.v1(request_handler, collector))

См. также: сбор HTTP-метрик

Объект коллектора.

См. также: создание пользовательских плагинов

Сбор наблюдений из данного коллектора. Для сбора наблюдений из каждого коллектора используйте metrics.collectors().

collector_object:collect() эквивалентен следующему коду:

 
for _, c in pairs(metrics.collectors()) do    for _, obs in ipairs(c:collect()) do        ...  -- handle observation    endend

Возвращает

Объединение объектов observation по всем созданным коллекторам.

 
{    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}

Тип возвращаемого значения

table

Объект счетчика.

Увеличивает наблюдение для label_pairs. Если label_pairs не существует, метод создает его.

Параметры:

• num (number) — значение приращения.
• label_pairs (table) — таблица, содержащая имена меток в качестве ключей, значения меток в качестве значений. Обратите внимание, что и имена, и значения меток в label_pairs обрабатываются как строки.

См. также: метки

Возвращает

Массив объектов observation для данного счетчика.

 
{    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}

Тип возвращаемого значения

table

Удаляет наблюдение для label_pairs.

Устанавливает значение 0 для наблюдения label_pairs.

Параметры:

• label_pairs (table) — таблица, содержащая имена меток в качестве ключей, значения меток в качестве значений. Обратите внимание, что и имена, и значения меток в label_pairs обрабатываются как строки.

Увеличивает наблюдение для label_pairs. Если label_pairs не существует, метод создает его.

Уменьшает наблюдение для label_pairs.

Устанавливает значение num для наблюдения label_pairs.

Возвращает массив объектов observation для данного измерителя. Описание observation см. в counter_obj:collect().

Удаляет наблюдение для label_pairs.

Записывает новое значение в гистограмму. При этом увеличиваются все размеры корзин под метками le >= num и метками, соответствующими label_pairs.

Параметры:

• num (number) — значение для помещения в гистограмму.
• label_pairs (table) — таблица, содержащая имена меток в качестве ключей, значения меток в качестве значений. Все внутренние счетчики, у которых указаны эти метки, фиксируют новые значения счетчиков. Обратите внимание, что и имена, и значения меток в label_pairs обрабатываются как строки. См. также: метки.

Возвращает объединение результатов counter_obj:collect() по всем внутренним счетчикам histogram_obj. Описание observation см. в counter_obj:collect().

Работает аналогично функции remove() счетчика.

Удаляет коллектор из реестра.

Параметры:

• collector (collector_obj) — удаляемый коллектор.

Пример:

 
local collector = metrics.gauge('some-gauge')-- after a while, we don't need it anymoremetrics.registry:unregister(collector)

Ищет коллектор в реестре.

Параметры:

• kind (string) — тип коллектора (counter, gauge, histogram или summary).
• name (string) — имя коллектора.

Возвращает

Объект коллектора или nil.

Тип возвращаемого значения

collector_obj

Пример:

 
local collector = metrics.gauge('some-gauge')collector = metrics.registry:find('gauge', 'some-gauge')

Записывает новое значение в сводку.

Параметры:

• num (number) — значение для помещения в поток данных.
• label_pairs (table) — таблица, содержащая имена меток в качестве ключей, значения меток в качестве значений. Все внутренние счетчики, у которых указаны эти метки, фиксируют новые значения счетчиков. Добавить метку "quantile" в сводку нельзя — она добавляется автоматически. Если заданы max_age_time и age_buckets_count, наблюдаемое значение добавляется в каждую корзину. Обратите внимание, что и имена, и значения меток в label_pairs обрабатываются как строки. См. также: метки.

Возвращает объединение результатов counter_obj:collect() по всем внутренним счетчикам summary_obj. Описание observation см. в counter_obj:collect(). Если заданы max_age_time и age_buckets_count, наблюдения квантилей собираются только из головной корзины в скользящем временном окне, а не из каждой корзины. Если наблюдения не были записаны, метод вернет NaN в значениях.

Работает аналогично функции remove() счетчика.