Autumn Docs

Оформление

Библиотека prometheus для OneScript ​

Библиотека prometheus даёт удобный способ собирать и экспортировать метрики в формате Prometheus Text Format в приложениях на OneScript.

Она решает две основные задачи:

  • Инструментирование кода: счётчики, gauge‑метрики, гистограммы, summary и пользовательские метрики.
  • Подготовка данных к сериализации: формирование промежуточного формата, совместимого с Prometheus, и передача его в функцию сериализации.

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

Установка ​

sh
opm install prometheus

После установки библиотеку можно подключить в проект так же, как и другие зависимости OneScript.

Базовые понятия ​

В библиотеке используются следующие сущности:

  • Регистр метрик — объект, который хранит все зарегистрированные метрики.
  • Семейство метрик — набор сэмплов с одинаковым именем и типом (counter, gauge, histogram, summary).
  • Сэмпл — одно значение метрики c набором лейблов.

На уровне API это выглядит как набор функций/классов для:

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

Быстрый старт: counter ​

Ниже — пример использования счётчика через фасадный модуль Prometheus.

  1. Регистрируем счётчик.
  2. Инкрементируем его при наступлении события.
  3. Собираем все метрики и сериализуем в текст.
bsl
#Использовать prometheus

// Регистрируем счётчик HTTP-запросов
HTTPRequestsTotal = Prometheus.НовыйСчетчик(
    "http_requests_total",
    "Всего HTTP-запросов"
);

// В обработчике запроса увеличиваем счётчик
Prometheus.Инкремент(HTTPRequestsTotal);

// Когда нужно отдать метрики, собираем и сериализуем
Семейства = Prometheus.СобратьМетрики(); // промежуточный формат
ТекстМетрик = Prometheus.СериализоватьВТекст(Семейства);

Результат сериализации будет выглядеть примерно так:

txt
# HELP http_requests_total Всего HTTP-запросов.
# TYPE http_requests_total counter
http_requests_total{method="get",code="200"} 1

Gauge‑метрики (gauge) ​

Gauge‑метрика хранит текущее значение (температура, размер очереди, свободная память и т.п.).

bsl
#Использовать prometheus

// Регистрируем gauge
QueueSize = Prometheus.НовыйИндикатор(
    "queue_size",
    "Текущий размер очереди"
);

// Устанавливаем значение
Prometheus.Установить(QueueSize, ТекущийРазмерОчереди());

В выходном формате Prometheus:

txt
# HELP queue_size Текущий размер очереди
# TYPE queue_size gauge
queue_size 42

Histogram и summary ​

Для анализа распределений и задержек используются типы histogram и summary. Типичный сценарий — измерить длительность операции:

bsl
#Использовать prometheus

// Регистрируем гистограмму с бакетами по времени
Границы = Новый Массив;
Границы.Добавить(0.1);
Границы.Добавить(0.5);
Границы.Добавить(1);
Границы.Добавить(5);

Duration = Prometheus.НоваяГистограмма(
    "request_duration_seconds",
    "Длительность обработки запроса в секундах",
    Границы
);

Начало = ТекущаяУниверсальнаяДатаВМиллисекундах();
// ... выполняем полезную работу ...
Конец = ТекущаяУниверсальнаяДатаВМиллисекундах();

ДлительностьВСекундах = (Конец - Начало) / 1000;
Prometheus.Наблюдать(Duration, ДлительностьВСекундах);

Сериализатор преобразует промежуточный формат в стандартный набор _bucket, _sum, _count в соответствии со спецификацией Prometheus.

Подробно структура промежуточного формата описана в файле docs/README.md: там расписаны поля семейств, сэмплов, правила сортировки бакетов и квантилей.

Интеграция с prometheus-metrics и Autumn ​

В большинстве случаев библиотека prometheus используется совместно с:

  • prometheus-metrics — веб‑сервисом, который поднимает эндпоинт GET /metrics;
  • Autumn и Winow — как инфраструктурой приложения и HTTP‑сервера.

Типичный сценарий:

  1. В приложении вы используете prometheus для регистрации и обновления метрик.
  2. prometheus-metrics встраивает контрол GET /metrics в ваше веб‑приложение.
  3. Контрол при вызове собирает метрики через prometheus, сериализует их и отдаёт в ответе.

Подробнее про встраивание контроллера и готовый пример см. в документации prometheus-metrics (она также доступна в доке Autumn как отдельный продукт).

Дальнейшее изучение ​

Руководство и концепции ​

  • Спецификация формата и сериализации — файл docs/README.md в репозитории prometheus.
  • Примеры использования и тесты — каталоги исходников и тестов библиотеки.

Справочник API ​

Интеграция ​

  • Пример полноценного HTTP‑эндпоинта /metrics — репозиторий prometheus-metrics.