ОтелДанныеМетрики
Данные одной метрики (MetricData): описание метрики и её точки данных.
Описание
ОтелДанныеМетрики передаёт данные метрики от источника к экспортёру. Экспортёр получает массив таких объектов в Экспортировать(МассивДанныхМетрик, Таймаут) (ОтелЭкспортерМетрик, свой экспортёр — ИнтерфейсЭкспортерМетрик), Prometheus-читатель переводит их в семейства Prometheus.
Данные создают:
- SDK — при сборе потока метрики читателем: точки формирует агрегатор потока, временную агрегацию проставляет читатель;
- продюсер метрик (ИнтерфейсПродюсерМетрик) — конструктором, из данных внешнего источника.
Объект хранит переданные значения как есть: конструктор их не проверяет и не копирует. Ресурс и область инструментирования обязательны: OTLP-экспортёр группирует по ним метрики в resourceMetrics и scopeMetrics, и с данными без них Экспортировать возвращает Ложь.
Конструктор
Новый ОтелДанныеМетрики(
Ресурс,
ОбластьИнструментирования,
Имя,
Описание,
ЕдиницаИзмерения,
ТипМетрики,
ТочкиДанных,
ФлагМонотонный,
Тип
)| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Ресурс | ОтелРесурс | — | Ресурс источника телеметрии. Продюсер передаёт ресурс, полученный в Произвести |
ОбластьИнструментирования | ОтелОбластьИнструментирования | — | Область инструментирования: у данных SDK — область метра, у данных продюсера — область, которая идентифицирует продюсер |
Имя | Строка | — | Имя метрики |
Описание | Строка | — | Описание метрики |
ЕдиницаИзмерения | Строка | — | Единица измерения, например "s" или "By" |
ТипМетрики | Строка | — | Тип метрики из ОтелТипМетрики: "sum", "gauge", "histogram", "exponentialHistogram" или "summary". От него зависят ключи точек данных |
ТочкиДанных | Массив из Соответствие | — | Точки данных, см. Точки данных |
ФлагМонотонный | Булево | Ложь | Монотонность суммы: Истина — сумма только растёт (счётчик) |
Тип | Строка | "int" | Тип значения точек суммы и датчика: "int" или "double" |
У нового объекта временная агрегация не задана (Неопределено) и метаданных нет: их задают УстановитьВременнуюАгрегацию и УстановитьМетаданные.
Точки данных
Точка данных — Соответствие с ключами OTLP JSON. Время — строка с числом наносекунд от начала эпохи Unix, например "1700000000500000000"; текущее время возвращает ТекущееВремяВНаносекундах() модуля ОтелУтилиты.
Ключи точек всех типов:
| Ключ | Тип | Описание |
|---|---|---|
attributes | Массив | Атрибуты точки в формате OTLP: массив соответствий {"key": ..., "value": {...}}, как возвращает ВМассивOtlp() объекта ОтелАтрибуты; без атрибутов — пустой массив |
startTimeUnixNano | Строка | Начало интервала, за который агрегированы значения. У датчика экспортёры его не используют |
timeUnixNano | Строка | Время точки — конец интервала |
exemplars | Массив из Соответствие | Необязательный: exemplars точки (см. ниже) |
Сумма (sum) и датчик (gauge):
| Ключ | Тип | Описание |
|---|---|---|
value | Число | Сумма или последнее значение. OTLP-экспортёр передаёт его в asDouble, если тип значения "double" или число дробное, иначе в asInt |
Гистограмма (histogram):
| Ключ | Тип | Описание |
|---|---|---|
count | Число | Количество измерений |
sum | Число | Сумма измерений. Может отсутствовать: SDK не собирает её у инструментов, которые могут записывать отрицательные значения (реверсивный счётчик, датчик) |
min, max | Число | Наименьшее и наибольшее измерение |
bucketCounts | Массив из Число | Количество измерений в бакетах; бакетов на один больше, чем границ |
explicitBounds | Массив из Число | Границы бакетов по возрастанию. В бакет с индексом i попадают значения больше границы i - 1 и не больше границы i, в последний бакет — больше последней границы |
Экспоненциальная гистограмма (exponentialHistogram):
| Ключ | Тип | Описание |
|---|---|---|
count | Число | Количество измерений |
sum | Число | Сумма измерений; может отсутствовать, как у гистограммы |
min, max | Число | Наименьшее и наибольшее измерение |
scale | Число | Шкала бакетов |
zeroCount | Число | Количество измерений в нулевом бакете |
zeroThreshold | Число | Порог нулевого бакета; OTLP-экспортёр передаёт его, только если он больше 0 |
positive, negative | Соответствие | Бакеты положительных и отрицательных измерений: offset — индекс первого бакета, bucketCounts — массив количеств измерений |
Сводка (summary) — её передают только продюсеры метрик:
| Ключ | Тип | Описание |
|---|---|---|
count | Число | Количество наблюдений |
sum | Число | Сумма наблюдений |
quantileValues | Массив из Соответствие | Квантили: quantile — уровень квантиля (например, 0.99), value — значение |
Exemplar — Соответствие в формате OTLP. Резервуары SDK заполняют ключи:
| Ключ | Тип | Описание |
|---|---|---|
timeUnixNano | Строка | Время измерения |
asDouble | Число | Значение измерения |
traceId, spanId | Строка | ID трассировки и спана в hex, если измерение синхронного инструмента записано в контексте валидного спана; у exemplars асинхронных инструментов этих ключей нет |
filteredAttributes | Массив | Атрибуты измерения, которых нет в атрибутах точки (их отбросил фильтр атрибутов потока), в формате OTLP; если таких атрибутов нет, ключа нет |
OTLP-экспортёр передаёт exemplars как есть (у сводки не передаёт), Prometheus-читатель выводит их в OpenMetrics у счётчиков и бакетов гистограмм.
Методы
Ресурс
Возвращает ресурс источника телеметрии.
Возвращает: ОтелРесурс
ОбластьИнструментирования
Возвращает область инструментирования.
Возвращает: ОтелОбластьИнструментирования
Имя
Возвращает имя метрики.
Возвращает: Строка
Описание
Возвращает описание метрики.
Возвращает: Строка
ЕдиницаИзмерения
Возвращает единицу измерения.
Возвращает: Строка
ТипМетрики
Возвращает тип метрики — значение ОтелТипМетрики. От него зависят ключи точек данных.
Возвращает: Строка — "sum", "gauge", "histogram", "exponentialHistogram" или "summary"
ТочкиДанных
Возвращает массив точек данных — тот же, что передан в конструктор: изменение массива или его точек меняет данные метрики.
Возвращает: Массив из Соответствие — см. Точки данных
Монотонный
Возвращает признак монотонности суммы. OTLP-экспортёр передаёт его в isMonotonic, Prometheus-читатель выводит монотонную сумму счётчиком (counter). SDK отмечает монотонными суммы инструментов, которые не записывают отрицательные значения, например счётчиков (синхронного и асинхронного).
Возвращает: Булево
ТипЗначения
Возвращает тип значения точек суммы и датчика. SDK задаёт "int" счётчикам и реверсивным счётчикам (синхронным и асинхронным), "double" — остальным инструментам.
Возвращает: Строка — "int" или "double"
ВременнаяАгрегация
Возвращает временную агрегацию, с которой собраны точки. Данным SDK её проставляет читатель: Кумулятивная() или Дельта() по виду инструмента (см. ОтелСелекторВременнойАгрегации). У данных продюсера она может быть не задана.
- OTLP-экспортёр передаёт её в
aggregationTemporalityсуммы, гистограммы и экспоненциальной гистограммы, а если она не задана — значение своего селектора для типа метрики. СОтелВременнаяАгрегация.НеУказана()экспорт прерывается с предупреждением в логе. У датчика и сводки временной агрегации в OTLP нет. - Prometheus-читатель пропускает сумму и гистограмму с
Дельта(), в лог пишется предупреждение.
Возвращает: Число, Неопределено — значение из ОтелВременнаяАгрегация; Неопределено — не задана
УстановитьВременнуюАгрегацию
Задаёт временную агрегацию точек. Продюсер метрик задаёт её, если знает, как источник накапливает значения.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Значение | Число, Неопределено | — | Значение из ОтелВременнаяАгрегация; Неопределено — не задана |
Метаданные
Возвращает метаданные метрики (metric.metadata в OTLP) — дополнительные сведения от источника данных. OTLP-экспортёр передаёт непустые метаданные в поле metadata. Prometheus-читатель берёт из ключа prometheus.type подсказку типа для датчика и немонотонной суммы: unknown, info или stateset (см. Подсказка типа датчика).
Возвращает: Соответствие — ключ → значение; пустое, если метаданных нет
УстановитьМетаданные
Задаёт метаданные метрики (metric.metadata).
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
Значение | Соответствие, Неопределено | — | Ключ → значение, значения — как у атрибутов (ОтелАтрибуты); Неопределено — метаданных нет |
Пример
Данные метрики в продюсере метрик (Ресурс — параметр Произвести):
// Счетчик из внешнего источника: монотонная кумулятивная сумма
Атрибуты = Новый ОтелАтрибуты();
Атрибуты.Установить("queue", "orders");
Точка = Новый Соответствие();
Точка.Вставить("attributes", Атрибуты.ВМассивOtlp());
Точка.Вставить("startTimeUnixNano", ВремяЗапуска); // строка, запомненная при запуске источника
Точка.Вставить("timeUnixNano", ОтелУтилиты.ТекущееВремяВНаносекундах());
Точка.Вставить("value", 42);
Точки = Новый Массив();
Точки.Добавить(Точка);
Область = Новый ОтелОбластьИнструментирования("queue-bridge", "1.0");
Данные = Новый ОтелДанныеМетрики(Ресурс, Область, "queue.messages.processed",
"Обработанные сообщения", "{message}", ОтелТипМетрики.Сумма(), Точки, Истина);
Данные.УстановитьВременнуюАгрегацию(ОтелВременнаяАгрегация.Кумулятивная());
// Сводка (Summary): квантили считает источник
Квантиль = Новый Соответствие();
Квантиль.Вставить("quantile", 0.99);
Квантиль.Вставить("value", 0.9);
Квантили = Новый Массив();
Квантили.Добавить(Квантиль);
Точка = Новый Соответствие();
Точка.Вставить("attributes", Новый Массив());
Точка.Вставить("startTimeUnixNano", ВремяЗапуска);
Точка.Вставить("timeUnixNano", ОтелУтилиты.ТекущееВремяВНаносекундах());
Точка.Вставить("count", 12);
Точка.Вставить("sum", 5.5);
Точка.Вставить("quantileValues", Квантили);
Точки = Новый Массив();
Точки.Добавить(Точка);
Сводка = Новый ОтелДанныеМетрики(Ресурс, Область, "rpc.duration", "Длительность вызовов", "s",
ОтелТипМетрики.Сводка(), Точки, Ложь, "double");Чтение данных в своём экспортёре:
Функция Экспортировать(МассивДанныхМетрик, Таймаут = Неопределено) Экспорт
Для Каждого Данные Из МассивДанныхМетрик Цикл
Если Данные.ТипМетрики() <> ОтелТипМетрики.Сумма() Тогда
Продолжить;
КонецЕсли;
Для Каждого Точка Из Данные.ТочкиДанных() Цикл
Сообщить(СтрШаблон("%1 = %2", Данные.Имя(), Точка.Получить("value")));
КонецЦикла;
КонецЦикла;
Возврат Истина;
КонецФункции