Autumn Docs

Оформление

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

Модули ​

Классы ​

Класс CollectorRegistry ​

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

Коллектор — объект с методом Collect(), который возвращает массив семейств метрик в промежуточном формате библиотеки (Имя, Тип, Справка, Сэмплы).

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

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

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

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

Методы ​

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

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

Параметры:

  • Коллектор — объект с методом Collect().

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

  • Булево — Истина (реестр не делает сложной валидации, но может быть расширен в будущем).

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

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

Параметры:

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

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

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

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

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

Алгоритм:

  1. Создаёт пустой массив ВсеСемейства.
  2. Для каждого коллектора из Коллекторы:
    • вызывает Коллектор.Collect(), получая массив семейств;
    • добавляет каждое семейство в ВсеСемейства.
  3. Возвращает ВсеСемейства.

Результат:

  • массив семейств метрик, готовый к дальнейшей обработке:
    • либо напрямую — через PrometheusTextFormat.Сериализовать;
    • либо через дополнительные преобразования (например, объединение со старыми коллекторами в PrometheusRegistry).

Модуль Prometheus ​

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

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

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

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

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

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

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

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

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

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

Создаёт и регистрирует счётчик (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).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сериализует массив семейств в строку в формате Prometheus Text Format. Использует модуль PrometheusTextFormat.

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

Возвращает строку Content-Type для HTTP‑ответа, совместимую с Prometheus:

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

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

Эти процедуры принимают структуру метрики (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 = верхней границе бакета;
    • Значение = накопленный счётчик (кумулятивная сумма).
  2. Добавляет бакет +Inf с суммарным количеством.
  3. Добавляет сэмпл _sum с суммой всех наблюдений.
  4. Добавляет сэмпл _count с количеством наблюдений.

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

Summary ​

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

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

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

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

  • увеличивает Сумма;
  • добавляет значение в Наблюдения;
  • обрезает массив до МаксНаблюдений (FIFO).

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

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

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

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

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

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

Модуль PrometheusRegistry ​

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

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

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

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

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

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

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

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

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

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

  • Если Коллектор — структура с полем Тип, то:
    • он считается старым коллектором;
    • добавляется в массив СтарыеКоллекторы;
    • возвращается Истина.
  • Иначе вызов делегируется в CollectorRegistry.Register(Коллектор) реестра по умолчанию.

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

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

  • для старых коллекторов — удаляет из массива СтарыеКоллекторы;
  • для обычных — вызывает CollectorRegistry.Unregister(Коллектор).

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

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

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

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

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

Сбор метрик ​

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

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

  1. Реестра по умолчанию (CollectorRegistry.Gather()).
  2. Массивa СтарыеКоллекторы, если он не пуст:
    • для векторных коллекторов (Тип = *_vector) вызывает PrometheusVec.СобратьВектор;
    • для остальных — PrometheusMetrics.СобратьКоллектор;
    • результаты преобразует в семейства с помощью СформироватьСемействаИзСэмплов и добавляет к общему результату.

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

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

Модуль PrometheusTextFormat ​

Модуль, отвечающий за сериализацию промежуточного формата метрик в строку в формате Prometheus Text Format.

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

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

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

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

Content-Type ​

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

Возвращает строку HTTP‑заголовка Content-Type:

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

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

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

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

Принимает массив семейств и возвращает строку в формате Prometheus:

  • сортирует семейства по имени;
  • для каждого семейства:
    • добавляет строку # HELP (если задана справка, с экранированием \ и перевода строки);
    • добавляет строку # TYPE (counter, gauge, histogram, summary или untyped);
    • выводит строки сэмплов.

Для histogram и summary выполняется дополнительная сортировка сэмплов:

  • Histogram:
    • бакеты _bucket сортируются по возрастанию le, +Inf идёт последним;
    • затем _sum, затем _count.
  • Summary:
    • сэмплы с quantile сортируются по возрастанию квантиля;
    • затем _sum, затем _count.

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

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

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

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

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

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

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

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

Модуль PrometheusVec ​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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