Перейти к содержанию

Аналитика и отчёты

Аналитика отвечает на вопросы «куда уходят токены и деньги», «кто и что делает», «как работает decision-слой» и «насколько эффективен промпт». Отчёты строятся по суточным агрегатам, поэтому не требуют отдельного аналитического хранилища и не раскрывают содержимое сообщений.

Что показывает

Семейство О чём отчёт
usage Токены на входе и выходе, кэш, стоимость по валютам, число вызовов
activity Созданные и заархивированные сессии, сообщения пользователя, ассистента и инструментов, вызовы инструментов, ошибки и прерывания
decision Вызовы decision-слоя, обработанные им запросы, fallback, эскалации, попытки и отказы
prompt Производные показатели: доля попаданий в кэш, доля reasoning-токенов, скорость генерации

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

Оси и время

Единица времени — сутки UTC (YYYY-MM-DD), а не часовой пояс инстанса. Отчёт можно сгруппировать по одной из осей:

Ось Что означает
День Сутки UTC
Пользователь Владелец сессии
Проект Проект сессии
Модель Модель, отвечавшая на запрос
Агент Роль агента, обрабатывавшего ход

usage раскладывается по пользователю, проекту, модели и агенту; activity — по пользователю и проекту; decision — по провайдеру и модели; prompt — проекция usage по модели и агенту. Детализация до отдельной сессии в роллапы не попадает: для одной сессии есть GET /api/v2/sessions/:id/stats.

Где смотреть

В интерфейсе отчёт открывается кнопкой «Аналитика и отчёты» в шапке (и в меню пользователя) и содержит вкладки:

  • «Расход и стоимость» — токены и деньги по выбранной оси;
  • «Активность» — сессии, сообщения, инструменты, ошибки;
  • «Decision» — decision-каскад и эскалации;
  • «Кэш и эффективность» — попадания в кэш, reasoning, скорость.

Период выбирается пресетом (7d, 30d, 90d) или произвольным диапазоном; фильтры — пользователь, проект, модель, агент. Таблицу можно отсортировать и выгрузить в CSV или JSON.

Те же данные доступны по API (только чтение):

GET /api/v2/analytics/summary?from&to
GET /api/v2/analytics/usage?from&to&groupBy=day|user|project|model|agent
GET /api/v2/analytics/activity?...
GET /api/v2/analytics/decision?...
GET /api/v2/analytics/prompt?...
GET /api/v2/analytics/export?report=usage|activity|decision|prompt&format=csv|json&...

CSV отдаётся в RFC 4180 с BOM и итоговой строкой TOTAL; JSON — это сам объект отчёта с сырыми счётчиками. Мутирующих методов у аналитики нет.

Кто что видит

Роль summary и decision usage, activity, prompt Экспорт
ADMIN, LEAD Сквозной обзор по инстансу Сквозной обзор Сквозной экспорт
AUDITOR Чтение Чтение Чтение
USER 403 Только своя ось пользователя Только своя ось; экспорт decision — 403

Обычный пользователь не видит чужие расходы и активность: фильтр по своей оси применяется принудительно, а не по выбору клиента. Роль AUDITOR читает отчёты, но не управляет ими; мутаций в контуре нет.

Пересборка роллапов

Роллапы — производные данные. Они пишутся на лету, но после восстановления из бэкапа, переноса между backend'ами или включения аналитики на существующем инстансе их можно пересобрать из накопленной истории.

synth analytics rebuild --from 2026-01-01 --dry-run
synth analytics rebuild --from 2026-01-01 --yes
  • --from <date> — начало окна включительно; по умолчанию вся история. Конец окна — сегодняшние сутки UTC.
  • --dry-run — только расчёт и сводка, ничего не пишется.
  • --yes — подтверждение перезаписи агрегатов. Без --yes и без --dry-run команда отказывается работать.
  • --json — машиночитаемая сводка.

Пересборка идемпотентна: повторный прогон не удваивает счётчики. usage и activity восстанавливаются из сообщений и истории сессий; decision не пересобирается, потому что истории метрик за прошлые периоды нет, а prompt — производное от usage. Схему базы команда не мигрирует.

Хранение и приватность

  • Роллапы хранятся сутками UTC; срок задаётся analytics.retentionDays (по умолчанию 400 дней, <= 0 — без ограничения) или переменной SYNTH_ANALYTICS_RETENTION_DAYS.
  • Очистка запускается при старте и далее каждые 6 часов.
  • В агрегатах нет текста сообщений, содержимого промптов, ключей и персональных данных — только счётчики и оси. Дериваты считаются на чтении и не хранятся.
  • Запись аналитики не влияет на ход сессии: ошибка агрегата не блокирует ответ. В деградированном режиме хранилища запись выключается.

Что дальше