Autumn Docs

Оформление

Модуль 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.