Перейти к основному содержанию
`Ctrl`+`K`

# Трассировка серверных вызовов и запросов

Инструмент фиксирует последовательность вызовов методов и SQL-запросов к базе данных, выполняемых в рамках одной сессии. Он позволяет анализировать, какие операции выполняются при пользовательских действиях (например, открытии класса или таблицы) или в фоновых процессах.

Трассировка — это ручной инструмент диагностики, предназначенный для разработчиков и администраторов. Он применяется для:

- точечного выявления причин замедлений в продуктивной системе;

- выявления узких мест производительности и избыточных вызовов;

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

- диагностики неожиданного поведения системы, когда явные ошибки отсутствуют;

- отладки фоновых операций, недоступных через интерфейс: заданий, интеграций, автоматических обработчиков.

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

Все результаты сохраняются в базе данных и доступны в виде структурированного отчёта через журнал трассировок.

## Запуск трассировки

### Типы трассировки

- Трассировка вызовов — фиксирует вызовы методов и SQL-запросы к базе данных.

- Трассировка запросов — фиксирует только SQL-запросы к базе данных.

### Трассировка собственных действий

Путь: `Сервис > Инструменты > Начать трассировку серверных вызовов` или `Сервис > Инструменты > Начать трассировку серверных запросов`.

1. Выберите тип трассировки.

2. Система начнёт запись.

3. Выполните нужные действия в интерфейсе (например, откройте таблицу).

4. Остановите запись одним из способов:

   - нажмите красный флажок в интерфейсе;

   - выберите `Сервис > Инструменты > Остановить трассировку`.

5. Откроется отчёт с результатами.

Трассировка завершится автоматически при закрытии сессии, даже если вы не остановили её вручную.

### Трассировка сторонней сессии

Администратор может запустить трассировку на любой активной сессии (пользователь, фоновая задача и т.д.).

Путь: `Сервис > Инструменты > Монитор сессии сервера приложений > Дополнительно`

1. Откройте монитор сессий.

2. Выберите нужную сессию.

3. Через меню Дополнительно запустите нужный тип трассировки.

4. Когда сессия выполнит интересующие вас операции, остановите трассировку одним из способов:

   - нажмите красный флажок в интерфейсе;

   - командой Завершить сессию.

5. Откроется стандартный отчёт с результатами.

Если сессия завершится сама (например, задача отработала), трассировка остановится автоматически.

### Трассировка заданий через карточку

Для фоновых задач можно включить трассировку напрямую в их настройках.

1. Откройте карточку задания.

2. Установите флаг Трассировка включена.

3. Сохраните изменения.

При следующем запуске задания система автоматически запишет трассировку. Результат появится в журнале трассировок.

### Вызов трассировки из кода

Трассировку можно запустить программно — из кода или Jexel-скрипта. Это полезно для отладки неотслеживаемых (не пользовательских) сессий.

Внимание

Трассировка сильно нагружает базу данных. Включайте её только при необходимости и обязательно привяжите к условию (например, к параметру контура или флагу в задаче).

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

- `ru.bitec.app.btk.intercept.Btk_ServerMethodInterceptPkg#startMethodIntercept()` — начать трассировку;

- `ru.bitec.app.btk.intercept.Btk_ServerMethodInterceptPkg#stopMethodIntercept()` — остановить трассировку;

- `ru.bitec.app.btk.intercept.Btk_ServerMethodInterceptPkg#getTraceID()` — получить идентификатор трассировки для последующего поиска в БД.

Эти методы доступны как в Java-коде, так и в Jexel-скриптах.

## Отчет трассировки

После остановки трассировки автоматически открывается отчёт с результатами. В нём отображаются три вкладки с разными группировками данных.

### Сгруппированный список

Группировка по отдельным методам и SQL-запросам. Для каждого элемента указано:

- общее количество вызовов;

- суммарное время выполнения всех вызовов.

### Список

Хронологический перечень всех вызовов. Если метод вызывался несколько раз — каждый вызов отображается отдельно.
Для каждого вызова можно посмотреть:

- Атрибуты — параметры, переданные в метод;

- Методанные — контекст вызова: откуда и каким действием был инициирован вызов;

- Результат — значение, возвращённое методом.

### Дерево вызовов

Древовидная структура, отображающая последовательность вызовов: какой метод вызвал какой, и какие SQL-запросы были выполнены внутри. Позволяет увидеть полную цепочку обработки конкретного действия.

### Сохранение отчёта

Отчёт можно сохранить в формате Excel:

- кликните правой кнопкой мыши по активной вкладке отчёта;

- выберите Сохранить как….

Совет

Сохраняется только текущая вкладка (одна из трёх группировок).

## Журнал трассировок

Все завершённые трассировки сохраняются в системе и доступны для повторного просмотра.

Путь: `Аудит > Журнал трассировки серверных методов`

В журнале отображаются записи с указанием:

- даты и времени начала трассировки;

- идентификатора трассировки (`id`);

- имени объекта трассировки.

Чтобы открыть отчёт, выберите запись и выполните операцию Открыть отчет трассировки.

Записи трассировок автоматически удаляются через 30 дней заданием `CleanupJob`.

## Отправка данных в систему мониторинга

Можно настроить отправку результатов трассировки в Grafana для дальнейшего анализа.

Путь: `Приложение Администратор > Настройки > Телеметрия > Объектные метрики`, выберите метрику Выполнение запросов БД.

Настройка сбора:

- укажите конкретных пользователей, которым будут приходить отчёты в Grafana;

- или включите галочку На всех пользователей, чтобы отчёты получали все.

Совет

В Grafana передаются только SQL-запросы. Вызовы методов в эту систему не попадают.

## Архитектура

Серверная трассировка работает на основе механизма динамического проксирования. При активации трассировки в сессии все пакеты (`Pkg`) и API-объекты пересоздаются через прокси-класс. Этот прокси перехватывает вызовы методов и SQL-запросов, фиксируя их параметры, контекст, время выполнения и результат.

### Формат данных

Данные записываются в таблицу `Btk_ServerMethodIntercept` и остаются привязанными к сессии до её завершения. Трассировка не вмешивается в логику выполнения, а лишь записывает последовательность вызовов, что сопровождается дополнительной нагрузкой на систему.

Каждый вызов сохраняется со следующими атрибутами:

- `id` — уникальный идентификатор вызова;

- `idParent` — идентификатор родительского вызова (для построения дерева);

- `nameMethod` — полное имя метода;

- `args` — аргументы вызова;

- `dateStart`, `dateEnd` — временные метки начала и окончания;

- `result` — возвращаемое значение;

- `bError` — признак ошибки (`true`/`false`).

Общая запись трассировки содержит:

- `id` — идентификатор трассировки;

- `jData` — JSON с полным деревом вызовов;

- `dDate` — дата создания;

- `gidObject` — привязка к объекту (например, `gid` задания);

- `sInfo` — дополнительная информация о сессии.

### Механизм записи данных

Данные трассировки не записываются в базу напрямую в реальном времени. Вместо этого используется буферизация в памяти.

Система ведёт три логических буфера:

- старт вызова метода;

- завершение вызова метода;

- выполнение SQL-запроса.

Запись в таблицу `Btk_ServerMethodIntercept` происходит пакетно: как только суммарное количество записей во всех буферах достигает 3000, выполняется автоматический сброс (flush), после которого буферы очищаются.