Autumn Docs

Аннотации ​

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

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

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

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

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

Размещение на конструкторе инструментирует все экспортные методы желудя, включая добавленные декоратором:

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

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

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

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

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

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

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

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

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

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

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

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

Записывает длительность каждого вызова метода в гистограмму OTel в секундах, как требуют семантические соглашения для гистограмм длительности. До версии 1.1.0 длительность писалась в миллисекундах.

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

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

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

Размещение на конструкторе инструментирует все экспортные методы желудя, включая добавленные декоратором:

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

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

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

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

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

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

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

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

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

Размещение на конструкторе инструментирует все экспортные методы желудя, включая добавленные декоратором:

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

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

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

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

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

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

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

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

Методы, добавленные декоратором ​

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

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

Пример с наследником: ПостроительНаследника собирает декоратор, в который переносит и методы родителя, и их аннотации.

bsl
&Замеряемый("orders.load.duration")
Функция ЗагрузитьЗаказ(ИдЗаказа) Экспорт
    Возврат Прочитать(ИдЗаказа);
КонецФункции
bsl
#Использовать extends

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

ЗагрузитьЗаказ попадёт в метрику orders.load.duration, хотя в модуле СервисЗаказов этого метода нет и определение желудя о нём не знает.