Autumn Docs

Публичный интерфейс библиотеки prometheus ​

Модули ​

Классы ​

Класс CollectorRegistry ​

Реестр коллекторов Prometheus.

Коллектор может быть:

  • структурой метрики с полем Тип (counter, gauge, histogram, summary, *_vector) — сбор через PrometheusMetrics / PrometheusVec внутри Gather();
  • объектом с методом Collect(), возвращающим массив семейств в промежуточном формате (Имя, Тип, Справка, Сэмплы).

Жизненный цикл ​

При создании:

  • инициализирует внутренний массив Коллекторы (список зарегистрированных коллекторов).

Обычно используется через модуль PrometheusRegistry, но может создаваться и использоваться вручную, если нужно несколько независимых реестров.

Методы ​

Функция Register(Коллектор) Экспорт ​

Регистрирует коллектор в реестре.

Параметры:

  • Коллектор — структура метрики (поле Тип) или объект с методом Collect().

Возвращаемое значение:

  • Булево — Истина, если коллектор зарегистрирован;
  • Ложь, если этот коллектор уже зарегистрирован или в реестре есть структура метрики с тем же Имя и такими же константными лейблами либо с тем же Имя и другим типом (counter и counter_vector считаются одним типом).

Метрики с одним именем выводятся одним семейством, поэтому допустимы только метрики одного типа с разными константными лейблами. Для объектов с Collect() проверяется только повторная регистрация того же объекта.

Функция Unregister(Коллектор) Экспорт ​

Снимает регистрацию коллектора.

Параметры:

  • Коллектор — ранее зарегистрированный объект.

Возвращаемое значение:

  • Булево — Истина, если коллектор найден и удалён;
  • Ложь, если такого коллектора в реестре нет.

Функция Gather() Экспорт ​

Собирает метрики со всех зарегистрированных коллекторов.

Алгоритм:

  1. Создаёт пустой массив ВсеСемейства.
  2. Для каждого элемента из Коллекторы:
    • если это структура с полем Тип — собирает сэмплы через PrometheusMetrics.СобратьКоллектор или PrometheusVec.СобратьВектор и группирует их в семейства;
    • иначе вызывает Коллектор.Collect() и добавляет возвращённые семейства;
    • каждое семейство попадает в ВсеСемейства.
  3. Объединяет семейства с одинаковым Имя в одно: поля берутся из первого семейства, сэмплы всех семейств собираются в новый массив. Массивы Сэмплы, которые вернули коллекторы, не меняются.
  4. Возвращает семейства в порядке первого появления имени.

Результат — массив семейств для PrometheusTextFormat.Сериализовать или модуля Prometheus при сборе.

Модуль Prometheus ​

Фасад для работы с библиотекой Prometheus:

  • создаёт метрики и векторы метрик;
  • регистрирует их в реестре по умолчанию;
  • предоставляет операции над метриками (инкремент, установка значения, наблюдение);
  • собирает метрики и сериализует их в текстовый формат Prometheus или OpenMetrics.

Реестр по умолчанию ​

Функция РеестрПоУмолчанию() Экспорт ​

Возвращает объект CollectorRegistry — реестр коллекторов метрик по умолчанию.

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

Создание скалярных метрик ​

Все фабрики принимают:

  • Имя — имя метрики;
  • Справка — строка # HELP (опционально);
  • КонстантныеЛейблы — соответствие имя → значение для лейблов, общих для всех сэмплов.

Повторное создание метрики с тем же именем и такими же константными лейблами (или с тем же именем и другим типом) вызывает исключение: метрика уже есть в реестре по умолчанию (см. CollectorRegistry.Register). Созданную метрику нужно сохранить и использовать повторно.

Функция НовыйСчетчик(Имя, Справка = "", КонстантныеЛейблы = Неопределено) Экспорт ​

Создаёт и регистрирует счётчик (counter), инициализированный нулём. Возвращает структуру метрики. Изменение значения выполняется через процедуры Инкремент и Добавить.

Функция НовыйИндикатор(Имя, Справка = "", КонстантныеЛейблы = Неопределено) Экспорт ​

Создаёт и регистрирует gauge‑метрику (gauge) с начальными значением 0. Изменяется через Установить, Инкремент, Декремент, Добавить, Вычесть.

Функция НоваяГистограмма(Имя, Справка = "", ВерхниеГраницыБакетов = Неопределено, КонстантныеЛейблы = Неопределено) Экспорт ​

Создаёт гистограмму (histogram):

  • ВерхниеГраницыБакетов — массив чисел для лейбла le;
  • счётчики бакетов, сумма и количество инициализируются нулями.

Наблюдения добавляются через процедуру Наблюдать.

Функция НовоеРезюме(Имя, Справка = "", Квантили = Неопределено, КонстантныеЛейблы = Неопределено) Экспорт ​

Создаёт summary‑метрику (summary):

  • Квантили — массив квантилей (по умолчанию 0.5, 0.9, 0.99);
  • хранит окно последних наблюдений и сумму значений.

Наблюдения добавляются через процедуру Наблюдать.

Векторы метрик ​

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

  • ИменаЛейблов — массив имён переменных лейблов (например ["method", "code"]);
  • КонстантныеЛейблы — соответствие для общих лейблов.

Функция НовыйСчетчикВектор(Имя, Справка, ИменаЛейблов, КонстантныеЛейблы = Неопределено) Экспорт ​

Создаёт и регистрирует вектор счётчиков (counter_vector).

Функция НовыйИндикаторВектор(Имя, Справка, ИменаЛейблов, КонстантныеЛейблы = Неопределено) Экспорт ​

Создаёт и регистрирует вектор gauge‑метрик (gauge_vector).

Функция НоваяГистограммаВектор(Имя, Справка, ИменаЛейблов, ВерхниеГраницыБакетов = Неопределено, КонстантныеЛейблы = Неопределено) Экспорт ​

Создаёт и регистрирует вектор гистограмм (histogram_vector).

Функция НовоеРезюмеВектор(Имя, Справка, ИменаЛейблов, Квантили = Неопределено, КонстантныеЛейблы = Неопределено) Экспорт ​

Создаёт и регистрирует вектор summary‑метрик (summary_vector). Без Квантили подметрики получают квантили по умолчанию (0.5, 0.9, 0.99), пустой массив оставляет только _sum и _count.

Получение экземпляра по лейблам ​

ЗначенияЛейблов можно передавать:

  • как массив, в том же порядке, что и ИменаЛейблов;
  • или как соответствие имя → значение.

Функция СчетчикСЛейблами(ВекторСчетчика, ЗначенияЛейблов) Экспорт ​

Возвращает конкретный счётчик с заданными лейблами.

Функция ИндикаторСЛейблами(ВекторИндикатора, ЗначенияЛейблов) Экспорт ​

Возвращает конкретный gauge с заданными лейблами.

Функция ГистограммаСЛейблами(ВекторГистограммы, ЗначенияЛейблов) Экспорт ​

Возвращает конкретную гистограмму с заданными лейблами.

Функция РезюмеСЛейблами(ВекторРезюме, ЗначенияЛейблов) Экспорт ​

Возвращает конкретное summary с заданными лейблами.

Сбор и сериализация ​

Функция СобратьМетрики(Реестр = Неопределено) Экспорт ​

Собирает метрики в промежуточный формат:

  • без параметра — использует реестр по умолчанию (PrometheusRegistry.Собрать);
  • с параметром Реестр — вызывает метод Gather() переданного объекта.

Возвращает массив семейств метрик.

Функция СериализоватьВТекст(Семейства, Формат = Неопределено) Экспорт ​

Сериализует массив семейств в строку в формате выдачи Формат (результат ВыбратьФормат). Без формата - в формате Prometheus Text Format 0.0.4. Использует модуль PrometheusTextFormat.

Функция ContentTypeМетрик(Формат = Неопределено) Экспорт ​

Возвращает строку Content-Type для HTTP‑ответа в формате выдачи Формат. Без формата - для text format 0.0.4:

txt
text/plain; version=0.0.4; charset=utf-8

Функция ВыбратьФормат(Accept) Экспорт ​

Выбирает формат выдачи по значению заголовка Accept HTTP-запроса: Prometheus Text Format 0.0.4 или 1.0.0, OpenMetrics 0.0.1 или 1.0.0, схема экранирования имён из параметра escaping. Без заголовка Accept - text format 0.0.4. Правила выбора описаны в модуле PrometheusTextFormat.

bsl
Формат = Prometheus.ВыбратьФормат(ЗаголовокAccept);
Текст = Prometheus.СериализоватьВТекст(Prometheus.СобратьМетрики(), Формат);
ТипКонтента = Prometheus.ContentTypeМетрик(Формат);

Унифицированные операции над метриками ​

Эти процедуры принимают структуру метрики (counter/gauge/histogram/summary) и вызывают соответствующие функции модуля PrometheusMetrics. Тип берётся из поля Метрика.Тип.

Процедура Инкремент(Метрика) Экспорт ​

  • Для counter — увеличивает значение на 1.
  • Для gauge — увеличивает значение на 1.
  • Для других типов — выбрасывает исключение.

Процедура Добавить(Метрика, Значение) Экспорт ​

  • Для counter — добавляет положительное число к значению (нельзя уменьшать).
  • Для gauge — добавляет число (может быть отрицательным).
  • Для других типов — выбрасывает исключение.

Процедура Установить(Метрика, Значение) Экспорт ​

  • Для gauge — устанавливает значение.
  • Для других типов — выбрасывает исключение.

Процедура Декремент(Метрика) Экспорт ​

  • Для gauge — уменьшает значение на 1.
  • Для других типов — выбрасывает исключение.

Процедура Вычесть(Метрика, Значение) Экспорт ​

  • Для gauge — вычитает число из значения.
  • Для других типов — выбрасывает исключение.

Процедура Наблюдать(Метрика, Значение) Экспорт ​

  • Для histogram — добавляет наблюдение в гистограмму.
  • Для summary — добавляет наблюдение в summary.
  • Для других типов — выбрасывает исключение.

Модуль PrometheusMetrics ​

Ядро, реализующее поведение конкретных типов метрик:

  • counter (счётчик);
  • gauge (индикатор);
  • histogram (гистограмма);
  • summary (резюме).

Модуль отвечает за:

  • создание внутренних структур метрик;
  • обновление их состояния (инкремент, добавление, установка, наблюдение);
  • преобразование состояния в сэмплы для промежуточного формата.

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

Counter ​

Функция НовыйСчетчик(Опции) Экспорт ​

Создаёт структуру счётчика со следующими полями:

  • Имя — имя метрики;
  • Справка — строка # HELP;
  • КонстантныеЛейблы — соответствие общих лейблов;
  • Значение — текущее значение (число);
  • Тип — строка "counter".

Процедура ИнкрементСчетчика(Счетчик) Экспорт ​

Увеличивает значение счётчика на 1 (некорректное начальное значение трактуется как 0).

Процедура ДобавитьКСчетчику(Счетчик, Значение) Экспорт ​

  • проверяет, что Значение — число;
  • не допускает отрицательных значений (счётчик не может уменьшаться);
  • добавляет Значение к текущему значению.

Процедура СобратьСчетчик(Счетчик, РезультатСэмплов) ​

Добавляет в массив РезультатСэмплов один сэмпл:

  • Имя = имя метрики;
  • Тип = "counter";
  • Справка = справка семейства;
  • ИмяСэмпла = имя метрики;
  • Лейблы = константные лейблы;
  • Значение = текущее значение.

Gauge ​

Функция НовыйИндикатор(Опции) Экспорт ​

Создаёт структуру индикатора:

  • Имя, Справка, КонстантныеЛейблы — аналогично счётчику;
  • Значение — начальное значение 0;
  • Тип — "gauge".

Процедура УстановитьИндикатор(Индикатор, Значение) Экспорт ​

Устанавливает значение индикатора.

Процедура ИнкрементИндикатора(Индикатор) Экспорт ​

Увеличивает значение на 1.

Процедура ДекрементИндикатора(Индикатор) Экспорт ​

Уменьшает значение на 1.

Процедура ДобавитьКИндикатору(Индикатор, Значение) Экспорт ​

Добавляет число к значению индикатора.

Процедура ВычестьИзИндикатора(Индикатор, Значение) Экспорт ​

Вычитает число из значения индикатора.

Процедура СобратьИндикатор(Индикатор, РезультатСэмплов) ​

Добавляет в РезультатСэмплов один сэмпл gauge‑метрики по тому же шаблону, что и для счётчика.

Histogram ​

Функция НоваяГистограмма(Опции) Экспорт ​

Создаёт структуру гистограммы:

  • Имя, Справка, КонстантныеЛейблы;
  • ВерхниеГраницыБакетов — массив чисел для лейбла le;
  • СчетчикиБакетов — массив счётчиков бакетов (лениво инициализируется нулями);
  • Сумма — сумма всех наблюдений;
  • Количество — количество наблюдений;
  • Тип — "histogram".

Процедура НаблюдатьГистограмму(Гистограмма, Значение) Экспорт ​

  • увеличивает Сумма и Количество;
  • при необходимости инициализирует СчетчикиБакетов;
  • для каждого бакета увеличивает счётчик, если Значение <= ВерхняяГраница.

Процедура СобратьГистограмму(Гистограмма, РезультатСэмплов) ​

Формирует набор сэмплов:

  1. Для каждого бакета:
    • ИмяСэмпла = Имя + "_bucket";
    • лейбл le = верхней границе бакета;
    • Значение = счётчик бакета — количество наблюдений <= le. Счётчики уже накоплены в НаблюдатьГистограмму, поэтому при сборе повторно не суммируются.
  2. Добавляет бакет +Inf с суммарным количеством.
  3. Добавляет сэмпл _sum с суммой всех наблюдений.
  4. Добавляет сэмпл _count с количеством наблюдений.

Все сэмплы относятся к одному семейству Имя / Тип = "histogram".

Summary ​

Функция НовоеРезюме(Опции) Экспорт ​

Создаёт структуру summary:

  • Имя, Справка, КонстантныеЛейблы;
  • Квантили — массив квантилей (по умолчанию 0.5, 0.9, 0.99);
  • Наблюдения — массив последних наблюдений;
  • МаксНаблюдений — максимум наблюдений в окне (по умолчанию 10000);
  • Сумма — сумма всех наблюдений;
  • Количество — число всех наблюдений, в том числе вышедших из окна;
  • Тип — "summary".

Процедура НаблюдатьРезюме(Резюме, Значение) Экспорт ​

  • увеличивает Сумма и Количество;
  • добавляет значение в Наблюдения;
  • обрезает массив до МаксНаблюдений (FIFO). Окно нужно только для квантилей: _sum и _count считаются по всем наблюдениям.

Процедура СобратьРезюме(Резюме, РезультатСэмплов) ​

  1. Сортирует Наблюдения по возрастанию.
  2. Для каждого квантиля q из Квантили:
    • находит соответствующее значение выборки;
    • добавляет сэмпл с лейблом quantile = q и значением квантиля.
  3. Добавляет сэмпл _sum с суммой наблюдений.
  4. Добавляет сэмпл _count с числом всех наблюдений (Количество).

Вспомогательные функции ​

Модуль также содержит функции:

  • ПолучитьОпцию, ПолучитьОпциюМассив, ПолучитьОпциюСоответствие — безопасное чтение параметров из структуры опций;
  • СкопироватьСоответствие — копирование соответствия лейблов;
  • СобратьКоллектор — диспетчер, вызывающий нужную Собрать*‑процедуру в зависимости от Коллектор.Тип.

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

Модуль PrometheusRegistry ​

Фасад над внутренним классом CollectorRegistry.

  • управляет реестром по умолчанию;
  • позволяет регистрировать/снимать регистрацию коллекторов;
  • собирает метрики из всех коллекторов и возвращает массив семейств в промежуточном формате.

Реестр по умолчанию ​

Функция ПолучитьРеестрПоУмолчанию() Экспорт ​

Ленивая инициализация объекта CollectorRegistry:

  • при первом вызове создаёт Новый CollectorRegistry();
  • далее возвращает уже созданный экземпляр.

Используется модулем Prometheus и может использоваться напрямую, если нужно управлять регистрацией коллекторов.

Регистрация коллекторов ​

Функция Зарегистрировать(Коллектор) Экспорт ​

Регистрирует коллектор в системе метрик.

Вызов делегируется в CollectorRegistry.Register(Коллектор) реестра по умолчанию.

Функция СнятьРегистрацию(Коллектор) Экспорт ​

Снимает регистрацию коллектора:

  • вызывает CollectorRegistry.Unregister(Коллектор).

Возвращает Истина, если коллектор был снят, иначе Ложь.

Процедура ЗарегистрироватьОбязательно(Коллектор) Экспорт ​

Обёртка над Зарегистрировать:

  • вызывает Зарегистрировать(Коллектор);
  • при неуспехе выбрасывает исключение, которое начинается с "Не удалось зарегистрировать коллектор метрик", а для структуры метрики содержит её имя. Неуспех означает, что этот коллектор уже зарегистрирован или в реестре есть метрика с тем же именем и такими же константными лейблами либо с другим типом (см. CollectorRegistry.Register).

Полезно при инициализации критичных метрик, без которых приложение не должно продолжать работу.

Сбор метрик ​

Функция Собрать() Экспорт ​

Собирает метрики из:

  • Реестра по умолчанию (CollectorRegistry.Gather()).

Возвращает массив семейств метрик:

  • каждое семейство — структура с полями Имя, Тип, Справка, Сэмплы;
  • структура соответствует промежуточному формату, описанному в спецификации библиотеки.

Модуль PrometheusTextFormat ​

Модуль, отвечающий за сериализацию промежуточного формата метрик в строку в формате Prometheus Text Format или OpenMetrics и за выбор формата выдачи по заголовку Accept HTTP-запроса (Content Negotiation).

Входной формат:

  • массив семейств метрик;
  • каждое семейство — структура с полями:
    • Имя — имя метрики;
    • Тип - counter, gauge, histogram, summary или untyped, а также info, stateset и unknown (см. Типы метрик);
    • Справка — строка # HELP (опционально);
    • Единица - единица измерения для строки # UNIT в OpenMetrics (опционально);
    • Сэмплы — массив сэмплов.

Сэмпл — структура с полями:

  • ИмяСэмпла — полное имя сэмпла (например, http_requests_total, metric_bucket);
  • Лейблы — соответствие имя → значение;
  • Значение — числовое значение;
  • для histogram: ВерхняяГраница (опционально, при формировании промежуточного формата);
  • для summary: Квантиль (опционально);
  • Экземпляр - exemplar для OpenMetrics (опционально): структура с полями Лейблы, Значение и необязательным Время (секунды);
  • Создано - время создания серии в секундах для сэмпла _created в OpenMetrics (опционально).

Формат выдачи ​

Формат выдачи - структура с полями:

  • Тип - "text" или "openmetrics";
  • Версия - версия формата;
  • Экранирование - схема экранирования имён (см. Экранирование имён);
  • ТипКонтента - значение заголовка Content-Type ответа.

Функция ФорматПоУмолчанию() Экспорт ​

Возвращает формат выдачи по умолчанию: text format 0.0.4 со схемой экранирования underscores.

Функция ВыбратьФормат(Accept) Экспорт ​

Выбирает формат выдачи по значению заголовка Accept:

  • поддерживаются text/plain версий 0.0.4 и 1.0.0 и application/openmetrics-text версий 0.0.1 и 1.0.0; без параметра version выбирается text format 0.0.4 или OpenMetrics 0.0.1;
  • */* и text/* соответствуют формату по умолчанию;
  • из поддерживаемых вариантов берётся вариант с наибольшим весом q, при равных весах - указанный раньше; вариант с q=0 не выбирается;
  • параметр escaping задаёт схему экранирования имён: underscores, dots, values или allow-utf-8; allow-utf-8 допустим только в форматах версии 1.0.0, в остальных случаях и для неизвестной схемы используется underscores;
  • без заголовка Accept или если ни один из запрошенных форматов не поддерживается, возвращается формат по умолчанию.

Пример:

bsl
Формат = PrometheusTextFormat.ВыбратьФормат("application/openmetrics-text;version=1.0.0,text/plain;q=0.5");
// Формат.ТипКонтента = "application/openmetrics-text; version=1.0.0; charset=utf-8; escaping=underscores"
Текст = PrometheusTextFormat.Сериализовать(Семейства, Формат);

Content-Type ​

Функция ContentType(Формат = Неопределено) Экспорт ​

Возвращает строку HTTP‑заголовка Content-Type для формата выдачи. Без формата - для text format 0.0.4:

txt
text/plain; version=0.0.4; charset=utf-8

Используется вместе с результатом Сериализовать при отдаче метрик по HTTP.

Сериализация ​

Функция Сериализовать(Семейства, Формат = Неопределено) Экспорт ​

Принимает массив семейств и формат выдачи (результат ВыбратьФормат, без формата - text format 0.0.4) и возвращает строку в этом формате:

  • сортирует семейства по имени; из семейств с одинаковым именем выводится последнее;
  • для каждого семейства:
    • добавляет строку # HELP (если задана справка, с экранированием \ и перевода строки, в OpenMetrics также ");
    • добавляет строку # TYPE (см. Типы метрик);
    • в OpenMetrics добавляет строку # UNIT, если задана Единица и имя семейства оканчивается на _<Единица>; у info и stateset строки # UNIT нет, их единица по спецификации пустая;
    • выводит строки сэмплов;
  • в OpenMetrics завершает выдачу строкой # EOF.

Для histogram и summary выполняется дополнительная сортировка сэмплов. Сначала сэмплы делятся на серии: в серию входят сэмплы с одинаковыми лейблами, не считая le у histogram и quantile у summary. Серии выводятся в порядке первого появления, каждая целиком:

  • Histogram:
    • бакеты _bucket сортируются по возрастанию le, +Inf идёт последним. le может быть числом или строкой с числом ("0.5"), как его формирует PrometheusMetrics;
    • затем _sum, затем _count.
  • Summary:
    • сэмплы с quantile сортируются по возрастанию квантиля;
    • затем _sum, затем _count.

Формат одной строки сэмпла ​

Строка имеет вид:

txt
имя_сэмпла{лейблы} значение

Лейблы формируются функцией СтрокаЛейблов:

  • лейблы сортируются по имени;
  • значения экранируются:
    • \ → \\;
    • перевод строки → \n;
    • " → \".

Числа форматируются функцией ФорматЧисла:

  • приводятся к числовому типу;
  • десятичный разделитель — точка (.).

В конце всегда добавляется перевод строки.

Типы метрик ​

ТипText formatOpenMetrics
countercountercounter, имя семейства без _total
gaugegaugegauge
histogramhistogramhistogram
summarysummarysummary
infogauge, имя с суффиксом _infoinfo, имя семейства без _info
statesetgaugestateset
unknownuntypedunknown
untypeduntypedunknown

В OpenMetrics имя сэмпла счётчика всегда оканчивается на _total, а имя сэмпла info в обоих форматах оканчивается на _info.

OpenMetrics ​

Кроме типов метрик, выдача OpenMetrics отличается от text format:

  • Создано выводится строкой <имя семейства>_created с лейблами серии: у счётчика после сэмпла значения, у histogram и summary после _count;
  • Экземпляр выводится после значения сэмпла в виде # {лейблы} значение [время], только у сэмплов счётчика и у бакетов histogram;
  • значения le у бакетов histogram и quantile у summary выводятся в канонической записи, как %g в Go с .0 у числа без дробной части и экспоненты: 1.0, 2.5, 100000.0, 1e+06, 1e-05. Запись, которая не является десятичным числом (+Inf), не меняется. В text format le и quantile выводятся как заданы.

Text format не поддерживает # UNIT, _created и exemplars: поля Единица, Создано и Экземпляр в нём не выводятся.

Пример выдачи OpenMetrics 1.0.0:

txt
# HELP jobs Задания
# TYPE jobs counter
jobs_total{queue="fast"} 5 # {trace_id="0af7651916cd43dd8448eb211c80319c"} 1 1700000003
jobs_created{queue="fast"} 1700000000.5
# EOF

Экранирование имён ​

Имя метрики или лейбла вне классического формата ([a-zA-Z_:][a-zA-Z0-9_:]*, в имени лейбла без :) выводится по схеме экранирования формата выдачи:

СхемаПравилоfoo.bar
underscores (по умолчанию)недопустимые символы заменяются на _foo_bar
dots_ → __, . → _dot_, прочие недопустимые символы → __foo_dot_bar
valuesпрефикс U__, _ → __, недопустимый символ → _<код символа в hex>_U__foo_2e_bar
allow-utf-8имя в кавычках; имя метрики выводится первым элементом в фигурных скобках{"foo.bar"}

Имена классического формата не меняются, кроме схемы dots: в ней _ всегда заменяется на __.

Модуль PrometheusVec ​

Модуль для работы с векторами метрик — фабриками, которые порождают отдельные метрики с разными наборами лейблов.

Поддерживает типы:

  • counter_vector;
  • gauge_vector;
  • histogram_vector;
  • summary_vector.

Используется фасадом Prometheus и модулем PrometheusRegistry.

Векторы метрик ​

Каждый вектор хранит:

  • имя метрики и справку;
  • имена переменных лейблов (ИменаПеременныхЛейблов);
  • константные лейблы;
  • внутреннее хранилище с подметриками.

Вектор сам по себе является коллектором: может собирать свои подметрики в виде массива сэмплов.

Получение метрики по лейблам ​

API ориентировано на две формы задания лейблов:

  • массив значений (в том же порядке, что ИменаПеременныхЛейблов);
  • соответствие ИмяЛейбла → Значение.

На уровне фасада Prometheus для этого используются функции:

  • СчетчикСЛейблами;
  • ИндикаторСЛейблами;
  • ГистограммаСЛейблами;
  • РезюмеСЛейблами.

Они делегируют работу модулю PrometheusVec, который:

  1. приводит значения к строкам, по одному на каждое имя из ИменаПеременныхЛейблов: недостающие значения (в том числе лейблы, которых нет в соответствии) становятся пустыми строками, лишние значения массива отбрасываются;
  2. ищет (или создаёт) подметрику с этим набором значений;
  3. возвращает структуру конкретной метрики (counter, gauge, histogram, summary), с которой дальше можно работать через PrometheusMetrics или фасад Prometheus.

Поэтому ("GET") и ("GET", "") для лейблов method и code возвращают одну и ту же подметрику.

У вектора summary без заданных Квантили подметрики получают квантили по умолчанию (0.5, 0.9, 0.99).

Сбор вектора ​

В модуле реализована процедура, используемая PrometheusRegistry:

  • СобратьВектор(Коллектор, РезультатСэмплов)

Она обходит все подметрики внутри вектора и дополняет массив РезультатСэмплов сэмплами в том же формате, что и PrometheusMetrics.СобратьКоллектор.

Эта процедура позволяет использовать векторы как полноправные коллекторы в реестре CollectorRegistry.

Редактировать страницу