Аналитика и отчёты¶
Аналитика отвечает на вопросы «куда уходят токены и деньги», «кто и что делает», «как работает 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'ами или включения аналитики на существующем инстансе их можно пересобрать из накопленной истории.
--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 часов.
- В агрегатах нет текста сообщений, содержимого промптов, ключей и персональных данных — только счётчики и оси. Дериваты считаются на чтении и не хранятся.
- Запись аналитики не влияет на ход сессии: ошибка агрегата не блокирует ответ. В деградированном режиме хранилища запись выключается.
Что дальше¶
- Публичный API и интеграции — ключи, scopes и выгрузка отчётов во внешние системы.
- Конфигурация — срок хранения роллапов и параметры хранилища.
- Метрики и наблюдаемость — операционные метрики, дополняющие отчёты.