Спостережимость и трассировка агентов (OpenTelemetry)

1. Обзор концепции и системная проблема

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

• Пользователь жалуется: "Агент отвечал 45 секунд и вернул чепуху".
• Без наблюдаемости разработчик не знает: модель зависла в размышлениях? Или инструмент поиска ответил с задержкой 40 секунд? Или агент сделал 12 ненужных повторных запросов из-за галлюцинации?
• Напоследок месяца компания получает счет на $15 000 вместо $1 500 из-за невидимого зацикленного воркера.

Agent Observability превращает хаос недетерминированного выполнения в прозрачную иерархическую структуру событий и спанов (Spans & Traces).

2. Архитектурная таксономия и ментальная модель

Trace ID: 7f8a91-bc42 (Total: 4.8s, Cost: $0.024)
┌─────────────────────────────────────────────────────────────┐
│ ROOT SPAN: User Task: "Analyze sales and generate summary"  │
│ ├── SPAN 1: LLM Reasoning (Claude 3.7) [1.2s, 1.4k tokens]  │
│ │   └── Output: Tool Call `query_database`                  │
│ ├── SPAN 2: Tool Execution: PostgreSQL [0.3s, 42 rows]     │
│ ├── SPAN 3: LLM Reasoning (Reflect on data) [0.9s]          │
│ │   └── Output: Tool Call `generate_chart`                  │
│ ├── SPAN 4: Tool Execution: Python Sandbox [1.8s]           │
│ └── SPAN 5: Final Response Synthesis [0.6s, 450 tokens]     │
└─────────────────────────────────────────────────────────────┘

Ключевые столпы наблюдаемости:

1. Traces & Spans: Полное дерево вызовов: каждый вызов модели или инструмента имеет время начала, продолжительность, входные аргументы и выходные результаты.
2. Token & Cost Attribution: Четкий учет затрат токенов (Input, Output, Cache Read, Cache Write) с разбивкой по отдельным фичам продукта.
3. Session Replay: Возможность пошагово воспроизвести состояние памяти агента в момент любого сбоя.

3. Практические инженерные сценарии в продакшене

01. Обнаружение аномальных утечек токенов

Алертинг в Slack срабатывает, если одна сессия агента превышает порог в 100 000 токенов или длится дольше 3 минут. Инженер просматривает трассу в Langfuse и видит, что модель застряла в исправлении одного и того же синтаксического конфликта.

02. Мониторинг кэширования промптов (Prompt Caching Hit-Rate)

Дашборд отслеживает процент запросов, которые попадают в статический кэш Anthropic/OpenAI. Если процент кэширования падает ниже 80%, это сигнализирует о том, что недавний коммит нарушил структуру префикса промпта.

4. Подводные камни, типовые ошибки и безопасность

• Overhead хранения (Storage Bloat): Запись полных промптов каждого пользователя при нагрузке 100 000 запросов/день может генерировать гигабайты логов в сутки. Используйте семплирование (Sampling Rate = 10% для успешных запросов, 100% для ошибок) и быстрые аналитические хранилища (ClickHouse).
• Утечка секретов в трассы: Если агент читает файл .env, содержание ключей может попасть в интерфейс мониторинга. Включайте регулярные выражения санитации на уровне клиентского SDK.

5. Стратегический вывод для инженера 2026 года

Наблюдаемость — это обязательное условие выхода агентов из лаборатории в реальный бизнес. То, что нельзя измерить и отслеживать по спанам, невозможно безопасно оптимизировать или масштабировать на сотни тысяч пользователей.