ИнтерфейсЭкспортерСпанов

Интерфейс экспортера спанов (SpanExporter) — методы, которые процессоры спанов вызывают у экспортера.

Описание

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

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

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

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

Экспортер передаётся процессору спанов, а процессор регистрируется в провайдере трассировки (ДобавитьПроцессор построителя ОтелПостроительПровайдераТрассировки):

• ОтелПростойПроцессорСпанов — Новый ОтелПростойПроцессорСпанов(Экспортер): экспортирует каждый спан при завершении, в потоке, который завершил спан;
• ОтелПакетныйПроцессорСпанов — собирается из Новый ОтелБазовыйПакетныйПроцессор(Экспортер, "traces"): копит спаны и экспортирует их пакетами в фоновом задании.

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

Методы

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

Экспортирует пакет завершённых спанов (Export). Метод не должен блокироваться бесконечно (спецификация, раздел Span Exporter): соблюдайте Таймаут, а когда он не передан — собственный предел (у ОтелЭкспортерСпанов — 10 000 мс). После Закрыть возвращайте Ложь.

Как процессоры вызывают метод:

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

Простой процессор вызывает метод с одним параметром, пакетный — с двумя, поэтому второй параметр должен быть необязательным. Экспортер, у которого Экспортировать принимает один параметр, от пакетного процессора не получит ни одного пакета.

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

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

---

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

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

Кто вызывает:

• простой процессор в своём СброситьБуфер — после завершения текущего экспорта, если тот завершился в срок, с временем, оставшимся до срока (0 — без ограничения). Параметр передаётся всегда, поэтому метод должен его принимать;
• простой процессор в Закрыть, пакетный — в СброситьБуфер и Закрыть, после экспорта накопленных спанов, если тот уложился в срок. Оставшееся время передаётся, если срок задан, иначе метод вызывается без параметра, поэтому параметр должен быть необязательным, как в интерфейсе.

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

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

---

Закрыть

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

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

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

Пример

Экспортер, который выводит завершённые спаны в консоль:

// Файл КонсольныйЭкспортерСпанов.os
Перем Закрыт;

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

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

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

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

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

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

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

Провайдер = Новый ОтелПостроительПровайдераТрассировки()
    .ДобавитьПроцессор(Новый ОтелПростойПроцессорСпанов(Новый КонсольныйЭкспортерСпанов()))
    .Построить();

Трассировщик = Провайдер.ПолучитьТрассировщик("my-library");
Спан = Трассировщик.НачатьСпан("обработка-заказа");
Спан.Завершить(); // простой процессор сразу передаёт спан экспортеру

Провайдер.Закрыть();

// С пакетным процессором
Базовый = Новый ОтелБазовыйПакетныйПроцессор(Новый КонсольныйЭкспортерСпанов(), "traces");
Процессор = Новый ПостроительНаследника(Новый ОтелПакетныйПроцессорСпанов(), Базовый).Построить();

См. также

• ОтелЭкспортерСпанов
• ОтелПростойПроцессорСпанов
• ОтелПакетныйПроцессорСпанов
• ИнтерфейсПроцессорСпанов
• ОтелРезультатыЭкспорта
• ОтелРезультатыЗакрытия