Логирование: structured logs
для агентов

Зачем логи, если есть трейсы

Логичный вопрос после трёх уроков про трейсинг: разве трейсы не покрывают всё? Нет — трейсы и логи решают разные задачи, и в проде нужны оба.

Трейс — это «микроскоп» на один запрос. Лог — «спутниковый снимок» всего потока: по логам строят алерты («ошибок > 1% за 5 минут»), считают частоты, ищут паттерны сбоев. Идеально они работают вместе — и связываются через общий trace_id (об этом ниже).

Почему structured, а не строки

Классический лог — это строка: "User 42 got error after 3 retries". Человеку читаемо, машине — беда. Чтобы найти «все ошибки пользователя 42», приходится парсить текст регэкспами, а любой рефактор сообщения ломает парсинг. Structured logging переворачивает подход: лог — это не строка, а объект с полями (обычно JSON).

Как только событие — это поля, всё становится возможным: «покажи все tool_error где tool=search и retries>=3 за последний час» — это запрос, а не археология по тексту. Плюс JSON-логи нативно принимают все системы агрегации (Grafana Loki, ELK/OpenSearch, Datadog, CloudWatch).

Уровни и что логировать

Не всё подряд и не молча. Два инструмента дозировки: уровни (насколько важно) и осознанный выбор что писать.

Уровни — стандартная лестница важности, чтобы в проде оставить нужное, а шум отключить:

• DEBUG — детали для локальной отладки (полные промпты, промежуточные шаги). В проде обычно выключен.
• INFO — нормальные бизнес-события: запрос принят, инструмент вызван, ответ отдан.
• WARNING — что-то не так, но система справилась: retry сработал, сработал fallback, близко к лимиту.
• ERROR — операция не удалась: инструмент упал, провайдер недоступен, запрос провалился.
• CRITICAL — система в опасности: отказ ключевой зависимости, невозможность обслуживать.

Что логировать у LLM-агента (события, специфичные для агентов):

Корреляция логов и трейсов

Логи и трейсы становятся по-настоящему мощными, когда связаны. Ключ связи — trace_id (из прошлого урока про OpenTelemetry): если каждая лог-запись несёт trace_id текущего запроса, то из алерта по логам ты одним кликом прыгаешь в полный трейс этого запроса, и наоборот.

Алерт: "ошибок tool_error > 1% за 5 мин"   (по ЛОГАМ — агрегация)
        │
        ▼  берём trace_id из лог-записи
Трейс запроса abc123                        (по ТРЕЙСУ — структура)
        │  видим: search вернул пусто → LLM галлюцинировал
        ▼
Фикс + лог с level=info "fallback_used"      (проверяем, что помогло)

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

Практика: structured logging на structlog

В Python стандартный logging умеет JSON, но популярнее structlog — он изначально про поля и контекст. Логика: настраиваешь JSON-рендер, привязываешь контекст запроса, пишешь события с полями.

import structlog

# 1. JSON-вывод в stdout (в проде это забирает агрегатор логов)
structlog.configure(
    processors=[
        structlog.processors.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer(),
    ]
)
log = structlog.get_logger()

def handle_request(user_id: str, question: str, trace_id: str):
    # 2. Контекст запроса → попадёт в КАЖДУЮ запись ниже автоматически
    request_log = log.bind(trace_id=trace_id, user_id=user_id)

    request_log.info("request_received")                       # INFO: бизнес-событие
    try:
        answer, usage = run_agent(question)
        request_log.info(
            "llm_call",                                        # поля, не строка!
            model="gpt-4o",
            input_tokens=usage.input, output_tokens=usage.output,
            cost=usage.cost, duration_ms=usage.ms,
        )
        return answer
    except ToolError as e:
        request_log.warning("fallback_used", reason=str(e))    # WARNING: справились
        return safe_fallback()
    except Exception as e:
        request_log.error("request_failed", error_type=type(e).__name__)  # ERROR
        raise

# Вывод (одна строка = один JSON-объект):
# {"event":"llm_call","level":"info","timestamp":"2026-07-19T...","trace_id":"abc123",
#  "user_id":"42","model":"gpt-4o","input_tokens":1120,"output_tokens":340,"cost":0.01}

Обрати внимание: trace_id и user_id задаются один раз через bind() и сами попадают во все последующие записи — вот та самая корреляция и контекст без ручного проброса.

Что НЕЛЬЗЯ логировать

Самая опасная часть. Логи у агентов особенно соблазнительно наполнить полными промптами и ответами — но там почти всегда есть чувствительное. Логи хранятся долго, копируются в агрегаторы, доступны многим — утечка через логи это классический инцидент.

• Секреты — API-ключи, токены, пароли, строки подключения. Никогда.
• PII — имена, email, телефоны, адреса, данные документов. Маскируй или не пиши.
• Полные промпты/ответы на INFO — там и PII, и объём. Для контента — трейсы (с маскированием) или DEBUG в деве, не прод-логи.
• Чувствительные бизнес-данные — платёжки, медзаписи и т.п. по требованиям комплаенса.

Типичные ошибки

Шпаргалка

3 СТОЛПА OBSERVABILITY: traces (структура) · metrics (числа) · LOGS (события)
  трейс = «микроскоп» на 1 запрос · лог = «спутник» на весь поток
  логи: дёшево, целиком, для поиска/агрегации/алертов

STRUCTURED > СТРОКИ: лог = JSON-объект с ПОЛЯМИ, не текст
  → фильтр (user_id=42 AND level=error) · агрегация · алерты · связь с трейсом
  правило: логи для МАШИН, сообщение вторично, поля главное
  принимают: Grafana Loki, ELK/OpenSearch, Datadog, CloudWatch

УРОВНИ: DEBUG (дев) · INFO (бизнес-события) · WARNING (справились: retry/fallback)
  · ERROR (операция упала) · CRITICAL (система в опасности)

ЧТО ЛОГИРОВАТЬ (агент): request принят/завершён · llm_call (model/tokens/cost)
  · tool_call · retry/fallback · error · РЕШЕНИЯ агента (какой tool, итерация)
  логируй ПОЧЕМУ решил, а не только результат

КОРРЕЛЯЦИЯ: trace_id в КАЖДОЙ записи → алерт по логам ↔ полный трейс
  bind(trace_id, request_id, user_id) один раз → во все записи запроса

НЕЛЬЗЯ: секреты · PII · полные промпты/ответы на INFO · чувствит. бизнес-данные
  ПРАВИЛО: логируй МЕТАДАННЫЕ, не содержимое (tokens/hash/длина, не сам текст)
  redaction на этапе логирования, не «почистим потом»

ГРАБЛИ: print вместо логгера · без trace_id · всё на одном уровне · всё «на всякий»

Практическое задание

Что дальше

Структурированные логи и трейсы дают сырые сигналы. Чтобы держать прод под контролем, из них строят дашборды: агрегированные метрики latency, cost, error rate и quality во времени — с алертами. Это финальный урок раздела Observability.