autumn-opentelemetry

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

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

Установка

opm install autumn-opentelemetry

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

OneScript 2.2.0+
opentelemetry >= 1.1.0
autumn >= 4.3.12

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

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

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

main.os

bsl

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

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

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

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

autumn-properties.json

json

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

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

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

bsl

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

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

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

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

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

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

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

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

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

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

Справочник API

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

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

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

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

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

autumn-properties.jsonПеременные окружения

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

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

json

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

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

Инструментирование entity

Параметры otel.entity.enabled, otel.entity.query-text и otel.entity.repository.enabled управляют трассировкой и метриками работы с базой данных через autumn-data. Признаки включения по умолчанию наследуют otel.enabled, текст запроса по умолчанию не пишется. Подробнее - в разделе Инструментирование entity.

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

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

autumn-properties.json

json

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

Аннотации

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

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

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

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

bsl

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

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

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

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

bsl

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

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

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

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

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

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

bsl

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

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

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

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

bsl

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

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

bsl

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

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

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

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

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

bsl

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

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

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

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

bsl

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

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

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

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

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

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

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

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

bsl

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

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

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

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

bsl

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

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

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

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

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

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

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

bsl

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

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

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

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

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

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

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

bsl

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

bsl

#Использовать extends

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

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

Инструментирование entity

Приложение на autumn-data получает трассировку и метрики работы с базой данных без единой строки прикладного кода: операции менеджера сущностей, запросы к СУБД, соединения, транзакции и вызовы хранилищ становятся спанами и метриками OpenTelemetry. Устроено как в Spring: слой данных инструментируется наблюдателем ORM, слой репозиториев - метрикой вокруг желудей.

Как это работает

ОтелДуб объявляет завязь ОтелНаблюдательИсточникаДанных с прозвищем НаблюдательИсточникаДанных - наблюдатель из библиотеки opentelemetry-instrumentation-entity.
autumn-data регистрирует все желуди с этим прозвищем на каждом источнике данных до создания менеджера сущностей.
НапильникОтелХранилищеСущностей оборачивает хранилища сущностей: желуди с прозвищем ХранилищеСущностей и пользовательские хранилища с аннотацией &ХранилищеСущностей.

Дерево спанов повторяет вызовы:

text

ПолучитьОдно Пользователь      INTERNAL  entity.type, entity.result.count
└─ SELECT Пользователи         CLIENT    db.system.name, db.query.text, server.address

Вызов метода хранилища собственного спана не получает: наблюдатель уже показывает ту же работу с той же длительностью, и второй спан был бы ее повтором. В трейсе метод виден по операциям, которые он выполнил, а сколько раз и как долго его звали - по гистограмме entity.repository.invocation.duration.

Когда нужен именно спан на методе хранилища - например, чтобы увидеть метод, который делает несколько операций подряд, - он вешается аннотацией &Наблюдаемый:

bsl

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

&МетодЗапроса
&Наблюдаемый
Функция ПолучитьОдноПоИмяРавно(Имя) Экспорт
КонецФункции

text

ХранилищеПользователей.ПолучитьОдноПоИмяРавно  INTERNAL  спан от &Наблюдаемый
└─ ПолучитьОдно Пользователь                   INTERNAL  entity.type, entity.result.count
   └─ SELECT Пользователи                      CLIENT    db.system.name, db.query.text

На отдельном методе аннотация покрывает только его. На конструкторе - все экспортные методы объекта, включая унаследованные от ХранилищеСущностей: на Получить и Сохранить тогда появится и спан аннотации, и спан операции entity - два спана об одном вызове с одинаковой длительностью. Если такой повтор не нужен, вешайте аннотацию на те методы, ради которых она нужна.

Сигналы

Сигнал	Имя	Источник
Гистограмма, с `entity.repository.invocation.duration`	`entity.repository`, `code.function.name`, `entity.repository.state` (`success`, `error`), `error.type`	напильник
Спаны операций и запросов, гистограммы `db.client.operation.duration` и `entity.operation.duration`, счетчики `entity.entities` и `entity.transactions`, датчики `db.client.connection.*`	см. opentelemetry-instrumentation-entity	наблюдатель

Оба сигнала пишет opentelemetry-instrumentation-entity: напильник находит желуди с прозвищем ХранилищеСущностей и отдает их инструментированию, а какие методы оборачиваются и что попадает в атрибуты - описано в его справочнике.

Трассировщик и метр наблюдателя - области entity; напильник использует желудь ОтелМетр, как и остальные напильники.

Настройки

Деталька	По умолчанию	Действие
`otel.entity.enabled`	`otel.enabled`	Завязь наблюдателя. При `false` завязь возвращает `Неопределено`, и менеджеры сущностей наблюдателя не получают; SDK при этом не поднимается
`otel.entity.query-text`	`false`	Текст запроса в атрибуте `db.query.text`. Запросы самого entity содержат плейсхолдеры вместо значений параметров, но произвольный текст из `ВыполнитьСКоннектором` не санитизируется и может нести литералы, поэтому по умолчанию выключено
`otel.entity.repository.enabled`	`otel.enabled`	Напильник слоя репозиториев

autumn-properties.jsonПеременные окружения

json

{
  "otel": {
    "enabled": true,
    "entity": {
      "enabled": true,
      "query-text": true,
      "repository": {
        "enabled": true
      }
    }
  }
}

OTEL_ENTITY_ENABLED=true
OTEL_ENTITY_QUERY_TEXT=false
OTEL_ENTITY_REPOSITORY_ENABLED=true

Датчики db.client.connection.* наблюдатель заполняет сам, из событий источника данных - что именно в них попадает, описано в его справочнике.

autumn-opentelemetry ​

Установка ​

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

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

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

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

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

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

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

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

Справочник API ​

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

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

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

Инструментирование entity ​

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

Аннотации ​

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

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

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

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

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

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

Инструментирование entity ​

Как это работает ​

Сигналы ​

Настройки ​

autumn-opentelemetry

Установка

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

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

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

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

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

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

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

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

Справочник API

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

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

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

Инструментирование entity

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

Аннотации

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

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

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

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

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

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

Инструментирование entity

Как это работает

Сигналы

Настройки