Логирование

OpenTelemetry Logs API позволяет собирать структурированные записи логов и экспортировать их в формате OTLP. Логи автоматически коррелируют с трассировкой через контекст — в каждую запись автоматически добавляются TraceId и SpanId текущего активного спана.

Архитектура

ОтелПровайдерЛогирования
    └── ОтелЛоггер
            └── ОтелЗаписьЛога

• ОтелПровайдерЛогирования — точка входа, создаёт логгеры.
• ОтелЛоггер — создаёт и отправляет записи логов.
• ОтелЗаписьЛога — запись с телом, уровнем серьёзности и атрибутами.

Создание провайдера через построитель

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

Ресурс = Новый ОтелРесурс();
Ресурс.Атрибуты().Установить("service.name", "my-service");

Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерЛогов(Транспорт);

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

Логгер = Провайдер.ПолучитьЛоггер("my-library", "1.0.0");

Создание записей лога

ОтелЗаписьЛога строится через Fluent API:

Простая запись

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

Логгер.Записать(Запись);

Запись с атрибутами

Запись = Логгер.СоздатьЗаписьЛога();
Запись.УстановитьТело("Запрос выполнен")
    .УстановитьСерьезность(ОтелСтепеньСерьезности.Info())
    .УстановитьАтрибут("user.id", "12345")
    .УстановитьАтрибут("http.method", "POST")
    .УстановитьАтрибут("http.status_code", 201);

Логгер.Записать(Запись);

Запись об ошибке

Попытка
    // ... работа ...
Исключение
    Запись = Логгер.СоздатьЗаписьЛога();
    Запись.УстановитьТело(ОписаниеОшибки())
        .УстановитьСерьезность(ОтелСтепеньСерьезности.Error())
        .УстановитьАтрибут("exception.type", "ОшибкаВыполнения");
    Логгер.Записать(Запись);
КонецПопытки

Уровни серьёзности

ОтелСтепеньСерьезности соответствует спецификации OpenTelemetry (числовые значения 1–24):

Метод	Числовое значение	Описание
ОтелСтепеньСерьезности.Trace()	1	Детальная трассировка
ОтелСтепеньСерьезности.Trace2() – Trace4()	2–4	Варианты Trace
ОтелСтепеньСерьезности.Debug()	5	Отладочная информация
ОтелСтепеньСерьезности.Debug2() – Debug4()	6–8	Варианты Debug
ОтелСтепеньСерьезности.Info()	9	Информационное сообщение
ОтелСтепеньСерьезности.Info2() – Info4()	10–12	Варианты Info
ОтелСтепеньСерьезности.Warn()	13	Предупреждение
ОтелСтепеньСерьезности.Warn2() – Warn4()	14–16	Варианты Warn
ОтелСтепеньСерьезности.Error()	17	Ошибка
ОтелСтепеньСерьезности.Error2() – Error4()	18–20	Варианты Error
ОтелСтепеньСерьезности.Fatal()	21	Критическая ошибка
ОтелСтепеньСерьезности.Fatal2() – Fatal4()	22–24	Варианты Fatal

Корреляция с трассировкой

Корреляция происходит автоматически. Если в момент записи лога активен спан, его TraceId и SpanId добавляются в запись:

// Трассировка уже инициализирована
Спан = Трассировщик.НачатьСпан("обработка", ОтелВидСпана.Внутренний());
Область = Спан.СделатьТекущим();

// Запись лога автоматически получит TraceId и SpanId из контекста
Запись = Логгер.СоздатьЗаписьЛога();
Запись.УстановитьТело("Начало обработки")
    .УстановитьСерьезность(ОтелСтепеньСерьезности.Info());
Логгер.Записать(Запись);

Область.Закрыть();
Спан.Завершить();

Интеграция с logos

ОтелАппендерLogos перенаправляет все сообщения библиотеки logos в OpenTelemetry. Это позволяет использовать привычный API logos, не меняя код.

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

Ресурс = Новый ОтелРесурс();
Ресурс.Атрибуты().Установить("service.name", "my-service");

Транспорт = Новый ОтелHttpТранспорт("http://localhost:4318");
Экспортер = Новый ОтелЭкспортерЛогов(Транспорт);
Процессор = Новый ОтелПростойПроцессорЛогов(Экспортер);

Провайдер = Новый ОтелПровайдерЛогирования(Ресурс, Процессор);
ОтелЛоггер = Провайдер.ПолучитьЛоггер("my-library", "1.0.0");

// Создаём аппендер и добавляем его к logos-логу
Аппендер = Новый ОтелАппендерLogos(ОтелЛоггер);

Лог = Логирование.ПолучитьЛог("oscript.app.myapp");
Лог.ДобавитьСпособВывода(Аппендер);

// Теперь все сообщения logos отправляются в OpenTelemetry
Лог.Информация("Приложение запущено");
Лог.Предупреждение("Конфигурация не найдена, используются значения по умолчанию");
Лог.Ошибка("Произошла ошибка: файл не найден");

Маппинг уровней logos → ОтелСтепеньСерьезности:

logos	OTel Severity
Отладка	Debug
Информация	Info
Предупреждение	Warn
Ошибка	Error

Мост логов → события спана

ОтелПроцессорСобытийВSpanEvents преобразует записи логов в события активного спана. Это удобно для отображения логов непосредственно в трассировке:

// Добавляем процессор, который пишет логи как span events
Провайдер = Новый ОтелПостроительПровайдераЛогирования()
    .УстановитьРесурс(Ресурс)
    .ДобавитьПроцессор(Новый ОтелПростойПроцессорЛогов(Экспортер))
    .ДобавитьПроцессор(Новый ОтелПроцессорСобытийВSpanEvents())
    .Построить();

Процессоры логов

Простой процессор (для разработки)

Процессор = Новый ОтелПростойПроцессорЛогов(Экспортер);

Пакетный процессор (для продакшена)

Процессор = Новый ОтелПакетныйПроцессорЛогов(Экспортер);

Пакетный процессор логов использует те же настройки OTEL_BSP_*, что и для спанов, но значение по умолчанию OTEL_BSP_SCHEDULE_DELAY = 1000 мс (вместо 5000 у спанов).

Композитный процессор

Процессор = Новый ОтелКомпозитныйПроцессорЛогов();
Процессор.ДобавитьПроцессор(Новый ОтелПакетныйПроцессорЛогов(Экспортер));
Процессор.ДобавитьПроцессор(Новый ОтелПроцессорСобытийВSpanEvents());

Смотрите также

• Автоконфигурация — настройка через OTEL_LOGS_EXPORTER
• Трассировка — корреляция логов со спанами
• Экспорт — эндпоинт /v1/logs
• API: ОтелЛоггер
• API: ОтелЗаписьЛога