Спостережуваність

Langfuse

Langfuse надає LLM observability — трейси, трекінг вартості та моніторинг якості.

Реалізація

src/observability/langfuse.ts

Конфігурація

Змінна	Обовʼязкова	Опис
LANGFUSE_PUBLIC_KEY	ні	Public-ключ (pk-lf-...)
LANGFUSE_SECRET_KEY	ні	Secret-ключ (sk-lf-...)
LANGFUSE_HOST	ні	URL сервера (дефолт: cloud.langfuse.com)

Langfuse опційний. Якщо ключі не налаштовані — трейсинг тихо вимикається.

Трейсовані операції

Span name	Компонент	Що трекається
intent.classify	Intent classifier	Input text, матчений intent, confidence
ingestion.synthetic-qa	Ingestion pipeline	Довжина контенту, згенеровані питання
rag.query	RAG pipeline	Query, retrieved chunks, scores, generation
generation	LLM calls	Модель, input/output tokens, latency, вартість

Модель даних

Трейси дзеркаляться локально у модель AgentRun:

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

Повʼязані RetrievalHit-записи трекають, які чанки були retrieved та їхні scores.

Перегляд трейсів

Через API

GET /api/v1/traces/:trace_id

Повертає AgentRun з усіма retrieval hits.

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

Перегляд:

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

---

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

Agent runner трекає кожну задачу і кроки tool-call у БД і бродкастить події реального часу через WebSocket.

Модель даних

Кожне вхідне повідомлення створює AgentTask із:

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

REST API

Ендпоінт	Призначення
GET /api/v1/agent-tasks	Список задач із фільтрами (namespace, department, status, adapter, date range)
GET /api/v1/agent-tasks/:id	Деталі задачі з tool-call трейсом
GET /api/v1/agent-tasks/stats	Агреговані метрики: success rate, avg duration, avg cost по adapter/namespace

Події реального часу (WebSocket)

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

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

Bull Board

Технічна queue-dashboard на /admin/queues (вимагає canEditSettings). Показує всі BullMQ-черги, включно з agent-tasks: статус задачі, retry count, failed job inspection.

---

Audit log

AgentCore автоматично логує усі мутації для compliance і дебагу.

Реалізація

src/middleware/audit.ts

Автоматичне логування

Audit-middleware перехоплює всі POST, PATCH і DELETE-запити та створює AuditLog-запис із:

Поле	Джерело
userId	JWT payload
action	Виводиться з метода + 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'],
});

Запит до логів

Список audit-логів

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

Авторизація: дозвіл canViewAudit.

Індекси

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

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