opentelemetry-instrumentation-entity

Инструментирование entity для OpenTelemetry SDK: операции менеджера сущностей, запросы к СУБД, соединения и транзакции его источника данных становятся спанами и метриками. Аналог инструментирования JDBC и Hibernate в Java: ORM ничего не знает об OpenTelemetry, а библиотека подписывается на его события через интерфейс НаблюдательИсточникаДанных.

Установка

opm install opentelemetry-instrumentation-entity

Требует entity 5.4 и OneScript 2.2: контекст исполнения обе библиотеки ведут в данных потока исполнения (ТекущийПоток).

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

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

Сдк = ОтелАвтоконфигурация.Инициализировать();

Источник = Новый ИсточникДанных("Основной", Тип("КоннекторPostgreSQL"), СтрокаСоединения);
Источник.ДобавитьНаблюдателя(Новый ОтелНаблюдательИсточникаДанных(
    Сдк.ПолучитьТрассировщик("entity"),
    Сдк.ПолучитьМетр("entity")
));

МенеджерСущностей = Новый МенеджерСущностей(Источник);
МенеджерСущностей.ДобавитьКлассВМодель(Тип("Автор"));
МенеджерСущностей.Инициализировать();

Авторы = МенеджерСущностей.Получить(Тип("Автор")); // спан "Получить Автор" с дочерним "SELECT Авторы"

Наблюдатель регистрируется на источнике данных и видит события всех менеджеров, созданных из него, включая создание таблиц при Инициализировать. В приложениях на Autumn регистрацию выполняет autumn-opentelemetry вместе с autumn-data, вручную ничего делать не нужно.

Вызовы методов хранилищ сущностей инструментируются отдельно — ОтелИнструментированиеХранилищаСущностей оборачивает хранилище сущностей и замеряет каждый вызов. Спанов эта обертка не создает: трейс строит наблюдатель источника данных.

Инструментирование = Новый ОтелИнструментированиеХранилищаСущностей(Сдк.ПолучитьМетр("entity"));

ХранилищеСущностей = Инструментирование.Обернуть(
    МенеджерСущностей.ПолучитьХранилищеСущностей(Тип("Автор")),
    "ХранилищеАвторы"
);

Сигналы

Сигнал	Имя	Атрибуты
Спан INTERNAL	`{Операция} {ТипСущности}` - `Сохранить Автор`, `Получить Автор`, `Инициализировать`	`code.namespace`, `code.function.name`, `entity.type`, `entity.table`, `entity.depth`, `entity.result.count`, `error.type`
Спан CLIENT	`{Операция} {Таблица}` - `SELECT Авторы`, `INSERT Авторы`, `COMMIT`	`db.system.name`, `db.namespace`, `db.collection.name`, `db.operation.name`, `db.query.text`, `db.response.returned_rows`, `server.address`, `server.port`, `error.type`
Гистограмма, с	`db.client.operation.duration`	`db.system.name`, `db.namespace`, `db.collection.name`, `db.operation.name`, `server.address`, `server.port`, `error.type`
Гистограмма, с	`entity.operation.duration`	`entity.operation`, `entity.type`, `error.type`
Счетчик	`entity.entities`	`entity.operation`, `entity.type`
Счетчик	`entity.transactions`	`entity.transaction.result`: `commit`, `rollback`, `failed`, `abandoned`
Датчик	`db.client.connection.count`	`db.client.connection.pool.name`, `db.client.connection.state`: `used`, `idle`
Датчик	`db.client.connection.max`, `db.client.connection.pending_requests`	`db.client.connection.pool.name`
Гистограмма, с	`db.client.connection.wait_time`, `db.client.connection.create_time`	`db.client.connection.pool.name`
Счетчик	`db.client.connection.timeouts`	`db.client.connection.pool.name`
Гистограмма, с	`entity.repository.invocation.duration`	`entity.repository`, `code.function.name`, `entity.repository.state` (`success` или `error`), `error.type`

Спаны вложены как вызовы: операция из прикладного кода - корень, разыменование ссылок и чтение подчиненных таблиц - дочерние операции, запросы к СУБД - листья. Каскад и N+1 видны как вложенность. BEGIN, COMMIT и ROLLBACK - обычные спаны запроса, долгоживущего спана транзакции нет.

Ключи db.*, server.*, error.type и code.* берутся из модуля ОтелСемантическиеСоглашения SDK и совпадают с semantic conventions OpenTelemetry; гистограммы длительности - в секундах с границами бакетов из соглашений. Ключи entity.* - собственные: значения в них могут быть кириллическими (имена операций и типов), ключи - латинские.

Текст запроса в db.query.text содержит плейсхолдеры, а не значения параметров. Описание соединения (db.namespace, server.address, имя пула) не содержит пароля.

Настройки

Третий параметр конструктора - структура настроек:

Ключ	По умолчанию	Действие
`ТекстЗапроса`	`Истина`	Писать текст запроса в `db.query.text`
`Метрики`	`Истина`	Регистрировать инструменты и писать метрики

Наблюдатель = Новый ОтелНаблюдательИсточникаДанных(Трассировщик, Метр, Новый Структура("ТекстЗапроса", Ложь));

Неопределено вместо трассировщика выключает спаны, вместо метра - метрики. Выключенный трассировщик SDK дает незаписывающие спаны, метрики при этом пишутся.

Документация

Лицензия

MIT License. Подробности в файле LICENSE.md.