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

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

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

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

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

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

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

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

1. Выберите тип трассировки.  
2. Система начнёт запись.  
3. Выполните нужные действия в интерфейсе (например, откройте таблицу).  
4. Остановите запись одним из способов:  
   - нажмите красный флажок в интерфейсе;  
   - выберите `Сервис > Инструменты > Остановить трассировку`.  
5. Откроется отчёт с результатами.

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

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

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

1. Откройте монитор сессий.  
2. Выберите нужную сессию.  
3. Через меню **Дополнительно** запустите нужный тип трассировки.  
4. Когда сессия выполнит интересующие вас операции, остановите трассировку одним из способов:  
   - нажмите красный флажок в интерфейсе;  
   - командой **Завершить сессию**.  
5. Откроется стандартный отчёт с результатами.

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

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

![trason](/img_nap/trasON.png)

1. Откройте карточку задания.  
2. Установите флаг **Трассировка включена**.  
3. Сохраните изменения.  

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

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

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

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

- `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-скриптах.

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

![ris](../img_nap/trace.png)

### Сгруппированный список  
Группировка по отдельным методам и SQL-запросам. Для каждого элемента указано:  
- общее количество вызовов;  
- суммарное время выполнения всех вызовов.

### Список  
Хронологический перечень всех вызовов. Если метод вызывался несколько раз — каждый вызов отображается отдельно.  
Для каждого вызова можно посмотреть:  
- **Атрибуты** — параметры, переданные в метод;  
- **Методанные** — контекст вызова: откуда и каким действием был инициирован вызов;  
- **Результат** — значение, возвращённое методом.

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

### Сохранение отчёта  
Отчёт можно сохранить в формате Excel:  
- кликните правой кнопкой мыши по активной вкладке отчёта;  
- выберите **Сохранить как...**.

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

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

Все завершенные трассировки сохраняются в системе и доступны для повторного просмотра. Подробное описание интерфейса журнала, хранимых данных, очистки и особенностей эксплуатации см. в разделе [«Журнал трассировки серверных методов»](https://help.globalerp.ru/books/GlobalUserGuideSystemWide/SNAPSHOT/html/service/010_audits_journals/04_%D0%A2%D0%B5%D1%85%D0%BD%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B5_%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB%D1%8B_%D0%B8_%D0%A1%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D0%BD%D1%8B%D0%B5_%D0%9B%D0%BE%D0%B3%D0%B8/001_%D0%96%D1%83%D1%80%D0%BD%D0%B0%D0%BB_%D1%82%D1%80%D0%B0%D1%81%D1%81%D0%B8%D1%80%D0%BE%D0%B2%D0%BA%D0%B8_%D1%81%D0%B5%D1%80%D0%B2%D0%B5%D1%80%D0%BD%D1%8B%D1%85_%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D0%BE%D0%B2.html).

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

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

![ris2](../img_nap/telemetr.png)

Настройка сбора:  
- укажите конкретных пользователей, которым будут приходить отчёты в Grafana;  
- или включите галочку **На всех пользователей**, чтобы отчёты получали все.

```{tip}
В 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), после которого буферы очищаются.