ИнтерфейсЭкспортерЛогов

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

Описание

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

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

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

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

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

• ОтелПростойПроцессорЛогов — Новый ОтелПростойПроцессорЛогов(Экспортер): экспортирует каждую запись сразу, в потоке, который её записал (внутри Логгер.Записать);
• ОтелПакетныйПроцессорЛогов — собирается из Новый ОтелБазовыйПакетныйПроцессор(Экспортер, "logs"): копит записи и экспортирует их пакетами в фоновом задании.

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

Методы

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

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

Записи экспортер только читает (ReadableLogRecord): ресурс и область инструментирования берутся из каждой записи (Ресурс(), ОбластьИнструментирования()).

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

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

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

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

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

---

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

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

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

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

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

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

---

Закрыть

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

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

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

Пример

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

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

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

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

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

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

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

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

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

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

Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .ДобавитьПроцессор(Процессор)
    .Построить();

Логгер = Провайдер.ПолучитьЛоггер("my-library");
Запись = Логгер.СоздатьЗаписьЛога();
Запись.УстановитьСерьезность(ОтелСтепеньСерьезности.Info()).УстановитьТело("Заказ создан");
Логгер.Записать(Запись);

Провайдер.Закрыть(); // финальный экспорт накопленных записей

См. также

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