Autumn Docs

Наблюдаемый ​

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

Синтаксис ​

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

Параметры ​

Значение ​

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

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

ВидСпана ​

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

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

Описание ​

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

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

Запись исключения пишется логгером ОтелЛоггер (область autumn-observed) по семантическим соглашениям exceptions-logs:

  • атрибуты exception.* ядро заполняет из исключения, к ним добавляется code.function.name, как у span'а;
  • серьёзность ERROR у span'ов вида server и consumer, WARN у остальных;
  • запись пишется до завершения span'а, поэтому процессор событий ядра, включённый в автоконфигурации по умолчанию, переносит её в событие span'а, и исключение видно в трассе.

error.type — значение ОтелУтилиты.ТипОшибки: код ошибки библиотеки errors, код нативной ошибки OneScript или _OTHER.

При размещении на конструкторе (вместе с &Желудь) инструментируются все экспортные методы желудя, в том числе те, которых нет в его модуле: напильник рефлексирует по самому экземпляру, а не по типу. К моменту обработки желудь обычно уже обёрнут декоратором — хранилищем сущностей autumn-data, построителем наследника из extends, декоратором предыдущего напильника, — и методов у экземпляра больше, чем объявлено в модуле типа.

Аннотации на методах читаются оттуда же, поэтому &Наблюдаемый на методе, пришедшем с декоратором, работает так же, как на методе самого желудя: задаёт имя и вид спана, а &АтрибутСпана на его параметрах - атрибуты. Такой метод инструментируется и тогда, когда на конструкторе аннотации нет вовсе.

Примеры ​

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

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

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

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

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

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

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

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

См. также ​