Проще говоря, structured logs - это логи по форме анкеты. У каждого события есть понятные поля: время, тип события, уровень, сервис, пользователь, workspace, trace id, request id, сценарий, статус, ошибка, длительность, стоимость, модель, tool name и другие параметры.
Для AI-агентов структурированные логи особенно важны. Обычный текстовый лог плохо объясняет, почему агент сделал действие. Нужны события по шагам: вход пользователя, выбранный route, вызов модели, token usage, tool calling, результат инструмента, guardrails decision, approval, fallback, финальный ответ и ошибка, если она была.
Structured logs отличаются от trace. Trace показывает цепочку событий внутри одного запуска, а structured logs фиксируют отдельные события в формате, удобном для поиска и метрик. На практике они работают вместе: каждый лог содержит trace_id, и по нему можно собрать весь путь запроса.
Хорошие structured logs помогают отвечать на реальные вопросы: какие сценарии чаще падают, какая модель дороже, где растет latency, какой tool дает больше ошибок, у каких клиентов превышен token budget, почему агент отправил запрос на approval и где появился prompt injection.
Важно не писать в логи все подряд. Prompt, документы, персональные данные, API-ключи, платежные реквизиты и коммерческие секреты нужно маскировать, хешировать или хранить отдельно с ограниченным доступом. Логи должны помогать отладке, а не становиться вторым небезопасным хранилищем данных.
Примеры
- AI-агент вызвал CRM tool. В structured log записались trace_id, tool_name, arguments_hash, status, latency_ms и error_code.
- Модель вернула невалидный structured output. Лог содержит schema_name, validation_error, model, prompt_version и retry_count.
- Guardrails заблокировали отправку письма. В событии есть decision=blocked, reason=missing_consent и contact_id.
- Token usage резко вырос. По логам видно, что в RAG-контекст попало слишком много document chunks.
- Telegram webhook получил update. Structured log хранит update_id, chat_id_hash, route, status и связанный task_id.
Где используется
- мониторинг AI-агентов в production
- поиск ошибок tool calling и API-интеграций
- связь событий с trace и agent session
- контроль token usage, latency и стоимости
- аудит guardrails, approval и blocked actions
- отладка webhook, task queue и outbox
- аналитика качества сценариев и evals
- расследование инцидентов безопасности
- дашборды по ошибкам, SLA и нагрузке
Связанные термины
Частые вопросы
Что такое structured logs простыми словами?
Это логи, где событие записано не свободным текстом, а набором полей: тип события, пользователь, trace id, статус, ошибка, длительность и другие данные.
Чем structured logs лучше обычных текстовых логов?
Их проще искать, фильтровать, строить по ним метрики и связывать события между собой. Например, быстро найти все ошибки конкретного tool или все дорогие запуски агента.
Какие поля логировать для AI-агента?
Минимум: timestamp, event, level, trace_id, user или workspace, scenario, model, status, latency, token usage, tool name, error code и guardrails или approval decision.
Structured logs и trace - это одно и то же?
Нет. Trace показывает цепочку выполнения одного запроса или запуска агента. Structured logs - отдельные события, которые удобно искать и агрегировать. Их связывают через trace_id.
Что нельзя писать в structured logs?
Нельзя без необходимости писать API-ключи, пароли, токены, платежные данные, полные персональные данные, приватные документы и полный prompt. Такие поля нужно маскировать или хранить отдельно.
