autumn-opentelemetry

autumn-opentelemetry — интеграция OpenTelemetry SDK с Autumn Framework.

Библиотека предоставляет аннотации для автоматической инструментации методов трассировкой, метриками и счётчиками, а также мост между логгером logos и OTel Logs API.

Установка

opm install autumn-opentelemetry

Совместимость

• OneScript 2.0.0+
• opentelemetry >= 1.0.0
• autumn >= 4.3.12

Быстрый старт

1. Подключение к приложению

autumn-opentelemetry подключается к приложению Autumn автоматически — достаточно добавить #Использовать autumn-opentelemetry:

main.os

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

Поделка = Новый Поделка();
Поделка.ЗапуститьПриложение();

2. Минимальная конфигурация

otel.enabled и otel.service.name — обязательные параметры:

autumn-properties.json

{
  "otel": {
    "enabled": true,
    "service": {
      "name": "my-service"
    }
  }
}

3. Инструментация методов

Классы/СервисЗаказов.os

&Желудь
&Наблюдаемый
Процедура ПриСозданииОбъекта()
КонецПроцедуры

&Подсчитываемый("orders.processed")
&Замеряемый("orders.duration")
Функция ОбработатьЗаказ(&АтрибутСпана("order.id") ИдЗаказа) Экспорт
    // span с атрибутом order.id = ИдЗаказа
    // длительность в гистограмме orders.duration
    // счётчик orders.processed инкрементируется
    Возврат СформироватьОтвет(ИдЗаказа);
КонецФункции

Основные возможности

ОтелДуб автоматически:

1. Инициализирует OpenTelemetry SDK через параметры приложения
2. Регистрирует бины ОтелSdk, ОтелТрассировщик, ОтелМетр
3. Создаёт и регистрирует аппендер ОтелАппендерLogos для экспорта логов

Аннотации доступны для любого &Желудь:

Аннотация	Описание
&Наблюдаемый	Создаёт span OpenTelemetry вокруг метода
&Замеряемый	Записывает длительность вызова в гистограмму
&Подсчитываемый	Инкрементирует счётчик при каждом вызове
&АтрибутСпана	Добавляет параметр метода как атрибут span'а

Дальнейшее изучение

Руководство пользователя

• Конфигурация — параметры OpenTelemetry и логирования
• Аннотации — подробное описание аннотаций с примерами

Справочник API

• Публичный интерфейс

---

Конфигурация

Обязательные параметры

Два параметра обязательны для запуска SDK:

Параметр	Описание
otel.enabled	Включает инструментирование аннотациями. При false SDK не инициализируется и экспортёры не запускаются.
otel.service.name	Имя сервиса в телеметрии.

autumn-properties.json

{
  "otel": {
    "enabled": true,
    "service": {
      "name": "my-service"
    }
  }
}

Переменные окружения

OTEL_ENABLED=true
OTEL_SERVICE_NAME=my-service

Экспорт телеметрии

По умолчанию SDK экспортирует трассы, метрики и логи по адресу http://localhost:4318 (протокол http/protobuf).

autumn-properties.json

{
  "otel": {
    "enabled": true,
    "service": {
      "name": "my-service"
    },
    "exporter": {
      "otlp": {
        "endpoint": "http://localhost:4318",
        "protocol": "http/protobuf"
      }
    },
    "traces":  { "exporter": "otlp" },
    "metrics": { "exporter": "otlp" },
    "logs":    { "exporter": "otlp" }
  }
}

Чтобы отключить SDK полностью:

autumn-properties.json

{
  "otel": {
    "sdk": {
      "disabled": true
    }
  }
}

Полный список параметров OpenTelemetry — в документации opentelemetry SDK.

Конфигурация логирования

ОтелДуб автоматически создаёт бин ОтелАппендерLogos и регистрирует его в logos. Для настройки уровня экспортируемых логов используйте autumn-properties.json:

autumn-properties.json

{
  "logos": {
    "logger": {
      "rootLogger": {
        "level": "INFO",
        "appenders": ["otel", "console"]
      }
    },
    "appender": {
      "otel": {
        "type": "ОтелАппендерLogos",
        "level": "WARN"
      },
      "console": {
        "type": "ВыводЛогаВКонсоль",
        "level": "INFO"
      }
    }
  }
}

---

Аннотации

&Наблюдаемый — трассировка методов

Автоматически создаёт span OpenTelemetry вокруг вызовов метода.

Размещение на отдельном методе инструментирует только его:

Классы/СервисЗаказов.os

&Желудь
Процедура ПриСозданииОбъекта()
КонецПроцедуры

&Наблюдаемый("orders.process")
Функция ОбработатьЗаказ(ИдЗаказа) Экспорт
    Возврат СформироватьОтвет(ИдЗаказа);
КонецФункции

Размещение на конструкторе инструментирует все экспортные методы класса:

Классы/СервисЗаказов.os

&Желудь
&Наблюдаемый
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Функция ОбработатьЗаказ(ИдЗаказа) Экспорт
    Возврат СформироватьОтвет(ИдЗаказа);
КонецФункции

Параметры аннотации:

Параметр	По умолчанию	Описание
Значение	"ИмяБина.ИмяМетода"	Имя span'а
ВидСпана	internal	Вид span'а: internal, server, client, producer, consumer

Пример с явным видом спана:

Классы/HttpКонтроллер.os

&Желудь
&Наблюдаемый(ВидСпана = "server")
Процедура ПриСозданииОбъекта()
КонецПроцедуры

&АтрибутСпана — атрибуты параметров

Добавляет значение параметра метода как атрибут текущего span'а. Используется совместно с &Наблюдаемый:

Классы/СервисЗаказов.os

&Наблюдаемый
Функция ОбработатьЗаказ(&АтрибутСпана("order.id") ИдЗаказа, Данные) Экспорт
    // span получит атрибут order.id = значение ИдЗаказа
    Возврат СформироватьОтвет(ИдЗаказа);
КонецФункции

Если Значение не указано — в качестве ключа атрибута используется имя параметра:

bsl

&АтрибутСпана          // ключ = "ИдЗаказа"
&АтрибутСпана("order.id")  // ключ = "order.id"

&Замеряемый — измерение длительности

Записывает длительность (в мс) каждого вызова метода в гистограмму OTel.

Атрибуты гистограммы: code.function.name, code.namespace, exception (при ошибке).

Классы/СервисПлатежей.os

&Желудь
Процедура ПриСозданииОбъекта()
КонецПроцедуры

&Замеряемый("payments.process.duration")
Функция ОбработатьПлатёж(Данные) Экспорт
    Возврат ПровестиПлатёж(Данные);
КонецФункции

Размещение на конструкторе инструментирует все экспортные методы:

Классы/СервисПлатежей.os

&Желудь
&Замеряемый
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Параметры аннотации:

Параметр	По умолчанию	Описание
Значение	"ИмяБина.ИмяМетода.duration"	Имя метрики (должно быть ASCII)

Имена методов на кириллице транслитерируются автоматически.

&Подсчитываемый — счётчик вызовов

Инкрементирует счётчик OTel при каждом вызове метода.

Атрибуты счётчика: code.function.name, code.namespace, result (success/failure), exception (при ошибке).

Классы/ApiКонтроллер.os

&Желудь
Процедура ПриСозданииОбъекта()
КонецПроцедуры

&Подсчитываемый("api.requests")
Функция ОбработатьЗапрос(Запрос) Экспорт
    Возврат СформироватьОтвет(Запрос);
КонецФункции

Размещение на конструкторе инструментирует все экспортные методы:

Классы/ApiКонтроллер.os

&Желудь
&Подсчитываемый
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Параметры аннотации:

Параметр	По умолчанию	Описание
Значение	"ИмяБина.ИмяМетода.counted"	Имя метрики (должно быть ASCII)

Имена методов на кириллице транслитерируются автоматически.

Комбинирование аннотаций

Аннотации можно комбинировать на одном методе:

Классы/СервисЗаказов.os

&Желудь
Процедура ПриСозданииОбъекта()
КонецПроцедуры

&Наблюдаемый("orders.process")
&Замеряемый("orders.duration")
&Подсчитываемый("orders.count")
Функция ОбработатьЗаказ(&АтрибутСпана("order.id") ИдЗаказа) Экспорт
    Возврат СформироватьОтвет(ИдЗаказа);
КонецФункции