ИнтерфейсЭкспортерМетрик

Интерфейс экспортера метрик (push MetricExporter) — методы, которые периодический читатель метрик вызывает у экспортера.

Описание

Экспортер отправляет собранные метрики во внешнюю систему: читатель метрик передаёт ему данные каждого сбора, экспортер кодирует их и передаёт по своему протоколу. Встроенная реализация — ОтелЭкспортерМетрик (OTLP). Свой экспортер пишут для приёмника, который не принимает OTLP, или для тестов.

Интерфейс — класс библиотеки с методами-заглушками и аннотацией &Интерфейс библиотеки extends. Класс экспортера объявляет, что реализует интерфейс, аннотацией &Реализует("ИнтерфейсЭкспортерМетрик") на конструкторе ПриСозданииОбъекта и определяет экспортные функции Экспортировать, СброситьБуфер и Закрыть. Кроме них читатель использует необязательные методы экспортера, если они есть: временную агрегацию и агрегацию по умолчанию задаёт экспортер (спецификация, раздел MetricReader).

SDK реализацию не проверяет: читатель принимает любой объект и ищет методы по имени при вызове. Проверить класс заранее, например в тесте, можно валидатором библиотеки extends: ИнтерфейсыРеализованыКорректно(Экспортер) объекта Новый ВалидаторРеализации() бросает исключение, если метода интерфейса нет или его нельзя вызвать с числом параметров метода интерфейса. Необязательные методы валидатор не проверяет.

Подключение экспортера

Экспортер передаётся ОтелПериодическийЧитательМетрик (Новый ОтелПериодическийЧитательМетрик(Экспортер, ИнтервалЭкспортаМс)), читатель регистрируется в провайдере метрик (ЗарегистрироватьЧитатель построителя ОтелПостроительПровайдераМетрик), а периодический сбор запускает Запустить() читателя.

Читатель не вызывает Экспортировать одновременно: сборы и экспорт идут по очереди. Повторной отправки читатель не делает: повторы — забота экспортера (спецификация, раздел Push Metric Exporter). СброситьБуфер и Закрыть могут вызываться одновременно с Экспортировать из другого потока — например, при закрытии провайдера во время фонового сбора, — поэтому они должны быть потокобезопасны (спецификация, раздел Concurrency requirements).

Методы

Экспортировать

Экспортирует данные сбора (Export). Читатель вызывает метод при каждом сборе: периодическом (после Запустить, раз в интервал), в своих СброситьБуфер, СброситьБуферБезОчистки и ПринудительноВыгрузитьСРезультатом (его вызывает СброситьБуфер провайдера метрик) и при финальном сборе в Закрыть. Если сбор не дал данных, метод не вызывается.

• Пакет — метрики сбора: инструментов SDK и продюсеров метрик читателя. Если задан МаксРазмерПакетаЭкспорта читателя, данные делятся на пакеты не больше этого числа точек и экспортируются по очереди; точки одной метрики могут попасть в разные пакеты — каждая часть передаётся отдельным ОтелДанныеМетрики.
• Таймаут — всегда число: меньшее из таймаута экспорта читателя (ТаймаутЭкспортаМс, по умолчанию 30 000 мс) и времени, оставшегося до срока операции; 0 — без ограничения. Метод не должен блокироваться бесконечно (спецификация, раздел Push Metric Exporter).
• Временную агрегацию данных показывает ОтелДанныеМетрики.ВременнаяАгрегация(). О данных с неподдерживаемой агрегацией или временной агрегацией экспортер должен сообщать как об ошибке: её исправляют настройкой читателя (спецификация, раздел MetricExporter). ОтелЭкспортерМетрик в этом случае пишет предупреждение в лог и возвращает Ложь.
• После Закрыть возвращайте Ложь.

Как читатель обрабатывает результат: Истина, успешный ОтелРезультатЭкспорта или успешный ОтелРезультатЗакрытия — успех. Любое другое значение, в том числе Неопределено, — сбой: таймаут, если экспортер вернул результат-таймаут или вызов длился дольше Таймаут, иначе ошибка. Исключение — ошибка и предупреждение в логе. Сбой экспорта делает результат сбора (СброситьБуфер, Закрыть читателя) ошибкой или таймаутом; данные неудачного экспорта читатель не хранит и повторно не отправляет. Результат периодического сбора никуда не передаётся, и Ложь читатель в лог не пишет: о причине сбоя экспортер сообщает сам.

Параметр	Тип	По умолчанию	Описание
МассивДанныхМетрик	Массив из ОтелДанныеМетрики	—	Данные метрик
Таймаут	Число	Неопределено	Срок экспорта в миллисекундах, 0 — без ограничения; читатель передаёт его всегда

Возвращает: Булево — Истина при успехе, Ложь при сбое; допускается и ОтелРезультатЭкспорта (ОтелРезультатыЭкспорта.Таймаут() читатель учитывает как таймаут)

---

СброситьБуфер

Как можно скорее завершает экспорт метрик, полученных до вызова (ForceFlush, спецификация, раздел Push Metric Exporter), в пределах таймаута. Экспортеру, который отправляет данные прямо в Экспортировать, делать нечего: он возвращает успех.

Вызывается из ПринудительноВыгрузитьСРезультатом читателя (ForceFlush, его вызывает СброситьБуфер провайдера метрик) после сбора и экспорта — даже если они завершились сбоем или срок уже истёк, — и только если у экспортера нет функции ПринудительноВыгрузитьСРезультатом. СброситьБуфер читателя этот метод не вызывает. Оставшееся время передаётся, если у метода есть параметр и срок задан (после срока — 1 мс), иначе метод вызывается без параметра — параметр должен быть необязательным, как в интерфейсе.

Параметр	Тип	По умолчанию	Описание
ТаймаутМс	Число	0	Срок в миллисекундах, 0 — без ограничения

Возвращает: ОтелРезультатЭкспорта — ОтелРезультатыЭкспорта.Успех(), Ошибка() или Таймаут(). Ложь читатель считает ошибкой, Неопределено — успехом, исключение — ошибкой

---

Закрыть

Завершает работу экспортера (Shutdown): освобождает ресурсы, после чего Экспортировать должен возвращать Ложь. Метод не должен блокироваться бесконечно (спецификация, раздел Push Metric Exporter).

Вызывается из Закрыть читателя (его вызывает Закрыть провайдера метрик) один раз: после финального сбора и экспорта, даже если они завершились сбоем, в пределах срока закрытия. Интерфейс объявляет метод без параметров; если у метода есть параметр и срок задан, читатель передаёт оставшееся время (после срока — 1 мс), иначе вызывает метод без параметра — такой параметр должен быть необязательным.

Возвращает: ОтелРезультатЗакрытия — ОтелРезультатыЗакрытия.Успех(), Ошибка(Описание) или Таймаут(). Неопределено считается успехом, Ложь — ошибкой, исключение — ошибкой с его описанием

Необязательные методы

Этих методов в интерфейсе нет: читатель вызывает их, если экспортер их определяет.

ПолучитьВременнуюАгрегацию

Возвращает временную агрегацию (temporality) для типа инструмента: читатель собирает потоки метрик с той временной агрегацией, которую задаёт экспортер. Вызывается при каждом сборе для каждого потока метрик. ОтелВременнаяАгрегация.Дельта() — дельта, любое другое значение — кумулятивная. Без метода, а также если он бросает исключение, все потоки собираются кумулятивно.

Готовые селекторы даёт ОтелСелекторВременнойАгрегации: селектор вызывается как Селектор.Применить(ТипИнструмента).

Параметр	Тип	По умолчанию	Описание
ТипИнструмента	Строка	—	"counter", "up_down_counter", "histogram" (и для экспоненциальной гистограммы), "gauge", "observable_counter", "observable_up_down_counter", "observable_gauge"

Возвращает: Число — значение из ОтелВременнаяАгрегация

---

АгрегацияПоУмолчанию

Возвращает агрегацию по умолчанию для вида инструмента. Читатель применяет её к потокам, для которых агрегацию не задали View и сам инструмент (экспоненциальная гистограмма получает свою агрегацию при создании), если читателю не задана своя агрегация для этого вида (УстановитьАгрегациюПоУмолчанию, агрегация гистограмм конструктора). Пустое значение — агрегация спецификации для вида. Агрегация, неизвестная или несовместимая с видом (например, гистограмма для асинхронного инструмента), заменяется агрегацией по умолчанию с предупреждением в логе.

Параметр	Тип	По умолчанию	Описание
ВидИнструмента	Строка	—	"Counter", "UpDownCounter", "Histogram", "Gauge", "ObservableCounter", "ObservableUpDownCounter", "ObservableGauge"

Возвращает: Строка, Соответствие — агрегация: "sum", "last_value", "explicit_bucket_histogram", "base2_exponential_bucket_histogram", "drop", "default" или конфигурация из ОтелАгрегация

---

ПринудительноВыгрузитьСРезультатом

Если метод есть, ПринудительноВыгрузитьСРезультатом читателя (ForceFlush) вызывает его вместо СброситьБуфер — так же: после сбора и экспорта, даже после их сбоя или истечения срока.

Параметр	Тип	По умолчанию	Описание
ТаймаутМс	Число	0	Время до срока в миллисекундах (после срока — 1 мс). Если срок не задан, метод вызывается без параметра, поэтому параметр должен быть необязательным

Возвращает: ОтелРезультатЗакрытия — результат сброса

Пример

Экспортер, который выводит метрики в консоль и собирает счетчики и гистограммы дельтами:

// Файл КонсольныйЭкспортерМетрик.os
Перем Закрыт;
Перем СелекторВременнойАгрегации;

Функция Экспортировать(МассивДанныхМетрик, Таймаут = Неопределено) Экспорт
    Если Закрыт Тогда
        Возврат Ложь;
    КонецЕсли;
    Для Каждого Данные Из МассивДанныхМетрик Цикл
        Сообщить(СтрШаблон("%1 (%2): точек данных %3",
            Данные.Имя(), Данные.ТипМетрики(), Данные.ТочкиДанных().Количество()));
    КонецЦикла;
    Возврат Истина;
КонецФункции

Функция СброситьБуфер(ТаймаутМс = 0) Экспорт
    // Своего буфера нет: данные выводятся в Экспортировать
    Возврат ОтелРезультатыЭкспорта.Успех();
КонецФункции

Функция Закрыть() Экспорт
    Закрыт = Истина;
    Возврат ОтелРезультатыЗакрытия.Успех();
КонецФункции

// Необязательный метод: без него читатель собирает все метрики кумулятивно
Функция ПолучитьВременнуюАгрегацию(ТипИнструмента) Экспорт
    Возврат СелекторВременнойАгрегации.Применить(ТипИнструмента);
КонецФункции

&Реализует("ИнтерфейсЭкспортерМетрик")
Процедура ПриСозданииОбъекта()
    Закрыт = Ложь;
    СелекторВременнойАгрегации = ОтелСелекторВременнойАгрегации.ПредпочтительноДельта();
КонецПроцедуры

Подключение:

#Использовать opentelemetry

ПодключитьСценарий(ОбъединитьПути(ТекущийСценарий().Каталог, "КонсольныйЭкспортерМетрик.os"),
    "КонсольныйЭкспортерМетрик");

Читатель = Новый ОтелПериодическийЧитательМетрик(Новый КонсольныйЭкспортерМетрик(), 60000);
Провайдер = Новый ОтелПостроительПровайдераМетрик()
    .ЗарегистрироватьЧитатель(Читатель)
    .Построить();
Читатель.Запустить();

Счетчик = Провайдер.ПолучитьМетр("my-library").СоздатьСчетчик("orders.created");
Счетчик.Добавить(1);

Провайдер.СброситьБуфер(); // сбор и экспорт, не дожидаясь интервала
Провайдер.Закрыть();

См. также

• ОтелЭкспортерМетрик
• ОтелПериодическийЧитательМетрик
• ОтелДанныеМетрики
• ОтелСелекторВременнойАгрегации
• ОтелРезультатыЭкспорта
• ОтелРезультатыЗакрытия