Справочник API

Библиотека дает два способа инструментирования entity — их можно включать по отдельности.

Класс	Назначение
ОтелНаблюдательИсточникаДанных	Наблюдатель источника данных: операции менеджера сущностей, запросы к СУБД, соединения и транзакции становятся спанами и метриками
ОтелИнструментированиеХранилищаСущностей	Обертка вокруг хранилища сущностей: точка гистограммы на каждый вызов метода

Наблюдатель регистрируется на источнике данных методом ИсточникДанных.ДобавитьНаблюдателя, обертка хранилища сущностей создается вызовом Обернуть.

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

Ключи db.*, server.*, error.type и code.* берутся из модуля ОтелСемантическиеСоглашения SDK, гистограммы длительности — в секундах.

---

ОтелИнструментированиеХранилищаСущностей

Инструментирование слоя хранилищ сущностей: оборачивает хранилище сущностей в декоратор, который пишет длительность каждого вызова метода в гистограмму. Аналог spring.data.repository.invocations в Spring Data.

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

Создание

Инструментирование = Новый ОтелИнструментированиеХранилищаСущностей(Метр);

Параметр	Тип	Назначение
ОтелМетр	ОтелМетр	Метр для гистограммы вызовов. Неопределено выключает инструментирование: Обернуть возвращает исходный объект

Обернуть

ХранилищеСущностей = Инструментирование.Обернуть(ХранилищеСущностей, "ХранилищеФизическиеЛица");

Параметр	Тип	Назначение
ХранилищеСущностей	Произвольный	Типизированное хранилище сущностей entity либо собственное
ИмяХранилищаСущностей	Строка	Имя в атрибуте entity.repository

Возвращает обертку с перехватчиками. Если оборачивать нечего, возвращается исходный объект — подменять его пустой оберткой незачем.

Оборачиваются экспортные методы фактического объекта, кроме тех, что не ходят в базу данных: ПолучитьОбъектМодели, ПолучитьПулСущностей, СоздатьЭлемент, Закрыть. Методы берутся с самого объекта, а не из его типа: у собственного хранилища сущностей не видно методов, унаследованных от ХранилищеСущностей, а у типизированного хранилища entity в типе нет ни одного.

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

Сигналы

Сигнал	Имя	Атрибуты
Гистограмма, с	entity.repository.invocation.duration	entity.repository, code.function.name, entity.repository.state (success или error), error.type

Исключение метода доходит до вызывающего кода как обычно, а точка гистограммы получает entity.repository.state со значением error и error.type — имя модуля, в котором исключение возникло, либо RuntimeError, если модуль неизвестен.

Границы бакетов гистограммы берутся из семантических соглашений для клиентов баз данных, длительность — в секундах.

Пример

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

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

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

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

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

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

// Точка гистограммы с entity.repository = ХранилищеФизическиеЛица и code.function.name = Получить,
// в трейсе - спаны операции и запроса от наблюдателя источника данных
Лица = ХранилищеСущностей.Получить();

См. также

• ОтелНаблюдательИсточникаДанных

---

ОтелНаблюдательИсточникаДанных

Наблюдатель источника данных entity, переводящий его события в спаны и метрики OpenTelemetry. Реализует интерфейс НаблюдательИсточникаДанных библиотеки entity.

Описание

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

Вид события entity	Спан	Метрики
Операция	INTERNAL {Операция} {ТипСущности}	entity.operation.duration, entity.entities
Запрос	CLIENT {Операция} {Таблица}	db.client.operation.duration
Соединение	-	db.client.connection.count, .max, .pending_requests, .wait_time, .create_time, .timeouts
Транзакция	-	entity.transactions

Конструктор

ПриСозданииОбъекта

&Реализует("НаблюдательИсточникаДанных")
Процедура ПриСозданииОбъекта(Знач ПТрассировщик, Знач ПМетр = Неопределено, Знач Настройки = Неопределено)

Параметры:

• ПТрассировщик - ОтелТрассировщик, Неопределено - трассировщик, которым создаются спаны. Неопределено выключает трассировку.
• ПМетр - ОтелМетр, Неопределено - метр, в котором регистрируются инструменты. Неопределено выключает метрики.
• Настройки - Структура, Неопределено - настройки наблюдателя:
  • ТекстЗапроса - Булево - писать текст запроса в атрибут db.query.text. По умолчанию Истина.
  • Метрики - Булево - регистрировать инструменты и писать метрики. По умолчанию Истина.

Инструменты метрик регистрируются в конструкторе, поэтому один метр на несколько наблюдателей (несколько источников данных) дает одни и те же инструменты: SDK возвращает уже зарегистрированный инструмент по имени.

Методы

ПередСобытием

Процедура ПередСобытием(Событие) Экспорт

Начинает спан операции или запроса с описательными атрибутами и делает его текущим. События соединений и транзакций спанов не порождают.

Параметры:

• Событие - СобытиеИсточникаДанных - начатое событие.

ПослеСобытия

Процедура ПослеСобытия(Событие) Экспорт

Дописывает в спан число строк и ошибку (событие exception, статус Error, атрибут error.type), закрывает область спана, завершает его и пишет метрики события.

Параметры:

• Событие - СобытиеИсточникаДанных - завершенное событие.

Пример

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

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