Наблюдаемость

Langfuse

Langfuse даёт наблюдаемость для LLM — трейсинг, учёт стоимости и контроль качества.

Реализация

src/observability/langfuse.ts.

Настройка

Переменная	Обязательная	Описание
LANGFUSE_PUBLIC_KEY	нет	Public key (pk-lf-...)
LANGFUSE_SECRET_KEY	нет	Secret key (sk-lf-...)
LANGFUSE_HOST	нет	URL сервера (дефолт cloud.langfuse.com)

Langfuse опционален. Если ключи не заданы, трейсинг автоматически отключается.

Отслеживаемые операции

Span name	Компонент	Что трекается
intent.classify	Intent classifier	Входной текст, матч intent, confidence
ingestion.synthetic-qa	Ingestion pipeline	Длина контента, сгенерированные вопросы
rag.query	RAG pipeline	Запрос, извлечённые чанки, скоры, генерация
generation	LLM-вызовы	Модель, input/output токены, latency, cost

Модель данных

Трейсы хранятся локально в модели AgentRun:

• traceId — ID трейса Langfuse;
• provider, model — информация о LLM-провайдере;
• inputTokens, outputTokens, totalTokens — использование токенов;
• costUsd — оценочная стоимость;
• latencyMs — время ответа.

Связанные записи RetrievalHit трекают, какие чанки были извлечены и их скоры.

Просмотр трейсов

Через API

GET /api/v1/traces/:trace_id

Возвращает AgentRun со всеми retrieval hits.

Через Langfuse-дашборд

Откройте дашборд Langfuse на настроенном LANGFUSE_HOST, чтобы увидеть:

• таймлайны трейсов;
• использование токенов во времени;
• разбивку стоимости по моделям;
• метрики качества.

---

Мониторинг agent tasks

Agent executor трекает каждую задачу и её шаги tool-call в БД и стримит realtime-события через WebSocket.

Модель данных

Каждое входящее сообщение создаёт AgentTask с полями:

• adapterType — какой адаптер обработал (api, claude_local, codex_local, ollama);
• status — состояние жизненного цикла (queued → running → completed/failed/timeout);
• использование токенов (inputTokens, outputTokens, totalTokens) и costUsd;
• durationMs — end-to-end время обработки;
• вложенные записи AgentToolCall на каждый шаг пайплайна.

REST API

Эндпоинт	Назначение
GET /api/v1/agent-tasks	Список задач с фильтрами (namespace, отдел, статус, адаптер, диапазон дат)
GET /api/v1/agent-tasks/:id	Деталь задачи с трейсом tool-call
GET /api/v1/agent-tasks/stats	Агрегированная статистика: success rate, средняя длительность, средняя стоимость по адаптеру/namespace

Realtime-события (WebSocket)

Подключитесь к ws://<host>/ws/agent-tasks, аутентифицируйтесь первым сообщением ({ "action": "auth", "token": "<jwt>" }), потом подпишитесь по namespace, чтобы получать живые события:

• agent-task.created — задача в очереди;
• agent-task.started — воркер забрал задачу;
• agent-task.tool-call — отдельный шаг выполнен (inject_profile, rag_search, generate, confidence_check, вызовы адаптера);
• agent-task.completed — задача завершена с выводом;
• agent-task.failed — задача упала или вышла по таймауту.

Bull Board

Админская панель очередей на /admin/queues (требует canEditSettings). Показывает все BullMQ-очереди, включая agent-tasks: статусы задач, retry count, инспекция упавших задач.

---

Журнал аудита

AgentCore автоматически логирует все мутации для compliance и отладки.

Реализация

src/middleware/audit.ts.

Автоматическое логирование

Audit middleware перехватывает все POST, PATCH и DELETE запросы и создаёт AuditLog с полями:

Поле	Источник
userId	Payload JWT
action	Выводится из method + URL (create/update/delete/approve/reject/escalate/login)
entityType	Выводится из пути URL
entityId	Извлекается из параметров URL
changes	Тело запроса (JSON)
ipAddress	IP клиента
userAgent	Заголовок user-agent клиента

Маппинг действий

URL-паттерн	Метод	Action
/auth/login	POST	login
/approvals/:id/approve	POST	approve
/approvals/:id/reject	POST	reject
/approvals/:id/escalate	POST	escalate
*	POST	create
*	PATCH	update
*	DELETE	delete

Явное логирование

Бизнес-логика может писать события напрямую:

import { logAuditEvent } from '../middleware/audit';

await logAuditEvent({
  userId: user.id,
  action: 'approve',
  entityType: 'approval',
  entityId: approval.id,
  changes: { status: 'approved' },
  ipAddress: request.ip,
  userAgent: request.headers['user-agent'],
});

Запрос логов

Список записей аудита

GET /api/v1/audit?action=approve&entityType=approval&userId=<id>&limit=50&offset=0

Требует право canViewAudit.

Индексы

Таблица AuditLog индексируется по:

• userId — фильтр по актору;
• (entityType, entityId) — фильтр по цели;
• createdAt — запросы по временному диапазону.