Публичный интерфейс библиотеки autumn-opentelemetry

Аннотации

• Наблюдаемый — создание span'ов вокруг методов
• Замеряемый — замер длительности методов
• Подсчитываемый — счётчик вызовов методов
• АтрибутСпана — добавление параметра метода как атрибута span'а

Классы

• ОтелДуб — конфигурационный модуль (дуб), регистрирует OTel-бины в контейнере Autumn

---

АтрибутСпана

Аннотация для добавления значения параметра метода в span как атрибут.

Синтаксис

&АтрибутСпана[(Значение)]

Параметры

Значение

Тип: Строка (опционально)

Ключ атрибута span'а (например, "order.id"). Если не указано, используется имя параметра.

Описание

Аннотация &АтрибутСпана применяется к параметрам методов, помеченных &Наблюдаемый. При вызове метода значение параметра автоматически записывается как атрибут текущего span'а с указанным ключом.

Пример

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

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

&Наблюдаемый
Функция Обработать(&АтрибутСпана ИдЗаказа) Экспорт
    // атрибут span'а: ИдЗаказа = значение ИдЗаказа
КонецФункции

См. также

• Наблюдаемый — создание span'ов вокруг методов

---

Замеряемый

Аннотация для автоматического замера длительности выполнения методов (аналог @Timed из Spring Boot).

Синтаксис

&Замеряемый[(Значение)]
Функция ИмяМетода(...) Экспорт
    ...
КонецФункции

Параметры

Значение

Тип: Строка (опционально)

Имя метрики. Должно соответствовать формату OTel (ASCII, точки как разделители). Если не указано, используется "ИмяБина.ИмяМетода.duration" с автоматической транслитерацией кириллицы.

Описание

Аннотация &Замеряемый оборачивает метод в декоратор, который:

1. Фиксирует время начала вызова
2. После завершения метода записывает длительность (в мс) в гистограмму OTel
3. При исключении записывает длительность с атрибутом exception

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

При размещении на конструкторе (вместе с &Желудь) инструментируются все экспортные методы класса.

Примеры

Инструментация одного метода

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

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

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

Комбинирование с другими аннотациями

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

См. также

• Наблюдаемый — создание span'ов вокруг методов
• Подсчитываемый — счётчик вызовов методов

---

Наблюдаемый

Аннотация для автоматического создания span'ов OpenTelemetry вокруг вызовов методов.

Синтаксис

&Наблюдаемый[(Значение [, ВидСпана])]
Функция ИмяМетода(...) Экспорт
    ...
КонецФункции

Параметры

Значение

Тип: Строка (опционально)

Имя span'а. Если не указано, используется "ИмяБина.ИмяМетода".

ВидСпана

Тип: Строка (опционально)

Вид span'а. Допустимые значения: internal (по умолчанию), server, client, producer, consumer.

Описание

Аннотация &Наблюдаемый оборачивает метод в декоратор, который:

1. Создаёт span с заданным именем и видом
2. Устанавливает атрибуты code.function.name и code.namespace
3. Делает span текущим в контексте OTel
4. Завершает span после выхода из метода (в том числе при исключении)
5. При исключении записывает его в span и устанавливает статус Error

При размещении на конструкторе (вместе с &Желудь) инструментируются все экспортные методы класса.

Примеры

Инструментация одного метода

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

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

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

С явным видом спана

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

С атрибутами параметров

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

См. также

• АтрибутСпана — добавление параметров метода как атрибутов span'а
• Замеряемый — замер длительности методов
• Подсчитываемый — счётчик вызовов методов

---

Подсчитываемый

Аннотация для автоматического подсчёта вызовов методов (аналог @Counted из Spring Boot).

Синтаксис

&Подсчитываемый[(Значение)]
Функция ИмяМетода(...) Экспорт
    ...
КонецФункции

Параметры

Значение

Тип: Строка (опционально)

Имя метрики. Должно соответствовать формату OTel (ASCII, точки как разделители). Если не указано, используется "ИмяБина.ИмяМетода.counted" с автоматической транслитерацией кириллицы.

Описание

Аннотация &Подсчитываемый оборачивает метод в декоратор, который:

1. Инкрементирует счётчик OTel при каждом вызове метода
2. Устанавливает атрибут result = "success" при успешном выполнении
3. При исключении устанавливает result = "failure" и записывает exception

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

При размещении на конструкторе (вместе с &Желудь) инструментируются все экспортные методы класса.

Примеры

Инструментация одного метода

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

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

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

Комбинирование с другими аннотациями

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

См. также

• Наблюдаемый — создание span'ов вокруг методов
• Замеряемый — замер длительности методов

---

ОтелДуб

Конфигурационный модуль (дуб) Autumn, регистрирующий бины OpenTelemetry в контейнере приложения.

Описание

ОтелДуб автоматически подключается при добавлении #Использовать autumn-opentelemetry в приложение Autumn. Явно создавать или настраивать его не нужно.

При инициализации регистрирует следующие бины:

Бин	Тип	Описание
МенеджерПараметров	МенеджерПараметров	Менеджер параметров приложения
ОтелSdk	ОтелSdk	Инициализированный SDK OpenTelemetry
ОтелАппендерLogos	ОтелАппендерLogos	Аппендер для экспорта логов logos через OTel Logs API
ОтелТрассировщик	ОтелТрассировщик	Трассировщик для области autumn-observed
ОтелМетр	ОтелМетр	Метр для области autumn-metrics

Ленивая инициализация

SDK инициализируется лениво — только при первом бине, требующем инструментирования. Если otel.enabled = false или в приложении нет бинов с аннотациями &Наблюдаемый / &Замеряемый / &Подсчитываемый, SDK не запускается и экспортёры не стартуют.

Использование бинов напрямую

Бины ОтелТрассировщик и ОтелМетр можно внедрять в свои классы через &Пластилин:

&Желудь
Процедура ПриСозданииОбъекта(&Пластилин Трассировщик)
    // Трассировщик — экземпляр ОтелТрассировщик
КонецПроцедуры

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

Поведение ОтелДуб управляется параметрами приложения. Подробнее — в разделе Конфигурация.