Autumn Docs

Модуль 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.
  • Для других типов — выбрасывает исключение.