Модуль 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 или если ни один из запрошенных форматов не поддерживается, возвращается формат по умолчанию.

Пример:

Формат = 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:

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.

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

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

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

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

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

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

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

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

Типы метрик

Тип	Text format	OpenMetrics
counter	counter	counter, имя семейства без _total
gauge	gauge	gauge
histogram	histogram	histogram
summary	summary	summary
info	gauge, имя с суффиксом _info	info, имя семейства без _info
stateset	gauge	stateset
unknown	untyped	unknown
untyped	untyped	unknown

В 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:

# 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: в ней _ всегда заменяется на __.