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

Аннотации

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

Классы

ОтелДуб — конфигурационный модуль (дуб), регистрирует OTel-желуди в контейнере Autumn
НапильникОтелХранилищеСущностей — гистограмма вызовов хранилищ сущностей autumn-data

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

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

Синтаксис

bsl

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

Параметры

Значение

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

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

Описание

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

Пример

bsl

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

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

bsl

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

См. также

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

Замеряемый

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

Синтаксис

bsl

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

Параметры

Значение

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

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

Описание

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

Фиксирует время начала вызова
После завершения метода записывает длительность (в секундах, единица s) в гистограмму OTel
При исключении записывает длительность с атрибутом exception

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

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

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

Примеры

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

bsl

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

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

bsl

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

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

bsl

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

См. также

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

Наблюдаемый

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

Синтаксис

bsl

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

Параметры

Значение

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

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

ВидСпана

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

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

Описание

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

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

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

Примеры

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

bsl

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

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

bsl

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

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

bsl

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

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

bsl

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

См. также

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

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

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

Синтаксис

bsl

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

Параметры

Значение

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

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

Описание

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

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

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

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

Примеры

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

bsl

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

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

bsl

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

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

bsl

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

См. также

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

НапильникОтелХранилищеСущностей

Напильник слоя хранилищ сущностей: находит в контейнере хранилища и отдает их инструментированию из opentelemetry-instrumentation-entity, которое замеряет вызовы методов гистограммой.

Описание

Применяется к желудям с прозвищем ХранилищеСущностей. Такое прозвище получают и хранилища, которые autumn-data регистрирует для каждой сущности, и пользовательские хранилища с аннотацией &ХранилищеСущностей.

Обертку строит ОтелИнструментированиеХранилищаСущностей — там же описано, какие методы оборачиваются и какие сигналы пишутся. Если оборачивать нечего, желудь остается нетронутым.

Спанов напильник не создает: вызов метода хранилища виден в метрике, а трейс строят операции entity и запросы к СУБД, которые метод выполнил. Спан на самом методе хранилища вешается аннотацией &Наблюдаемый — на конструкторе желудя или на отдельном методе.

Порядок: &Порядок(503) - после напильников аннотаций.

Конструктор

bsl

&Напильник
&Порядок(503)
Процедура ПриСозданииОбъекта(&Табакерка &Пластилин("ОтелМетр") ОтелМетр,
		&Деталька(Значение = "otel.enabled", ЗначениеПоУмолчанию = Ложь) ОтелВключен,
		&Деталька(Значение = "otel.entity.repository.enabled", ЗначениеПоУмолчанию = "") СлойВключен)

Напильник включен, когда включен otel.enabled и не выключен otel.entity.repository.enabled. Метр достается из табакерки при первом обернутом желуде, поэтому SDK не поднимается, если хранилищ в приложении нет.

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

Подробнее - в разделе Инструментирование entity.

ОтелДуб

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

Описание

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

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

Жёлудь	Тип	Описание
`МенеджерПараметров`	`МенеджерПараметров`	Менеджер параметров приложения
`ОтелSdk`	`ОтелSdk`	Инициализированный SDK OpenTelemetry
`ОтелАппендерLogos`	`ОтелАппендерLogos`	Аппендер для экспорта логов logos через OTel Logs API
`ОтелТрассировщик`	`ОтелТрассировщик`	Трассировщик для области `autumn-observed`
`ОтелМетр`	`ОтелМетр`	Метр для области `autumn-metrics`
`ОтелНаблюдательИсточникаДанных`	`ОтелНаблюдательИсточникаДанных`	Наблюдатель entity с прозвищем `НаблюдательИсточникаДанных`: спаны и метрики источников данных `autumn-data`. При выключенном `otel.entity.enabled` завязь возвращает `Неопределено`

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

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

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

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

bsl

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

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

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

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

Аннотации ​

Классы ​

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

Синтаксис ​

Параметры ​

Значение ​

Описание ​

Пример ​

См. также ​

Замеряемый ​

Синтаксис ​

Параметры ​

Значение ​

Описание ​

Примеры ​

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

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

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

См. также ​

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

Синтаксис ​

Параметры ​

Значение ​

ВидСпана ​

Описание ​

Примеры ​

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

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

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

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

См. также ​

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

Синтаксис ​

Параметры ​

Значение ​

Описание ​

Примеры ​

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

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

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

См. также ​

НапильникОтелХранилищеСущностей ​

Описание ​

Конструктор ​

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

ОтелДуб ​

Описание ​

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

Использование желудей напрямую ​

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

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

Аннотации

Классы

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

Синтаксис

Параметры

Значение

Описание

Пример

См. также

Замеряемый

Синтаксис

Параметры

Значение

Описание

Примеры

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

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

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

См. также

Наблюдаемый

Синтаксис

Параметры

Значение

ВидСпана

Описание

Примеры

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

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

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

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

См. также

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

Синтаксис

Параметры

Значение

Описание

Примеры

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

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

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

См. также

НапильникОтелХранилищеСущностей

Описание

Конструктор

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

ОтелДуб

Описание

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

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

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