voidea/template/docs/09-logging.md

Логирование

---

Формат строки лога

[ISO8601] [LEVEL] [component] message key=val

Пример:

2026-05-10T14:30:00.000Z INFO [auth] User logged in user_id=abc123
2026-05-10T14:30:01.000Z WARNING [ai] Yandex GPT timeout retry=1 max_retries=2
2026-05-10T14:30:02.000Z ERROR [sync] Sync failed for user_id=abc123 error="Connection refused"

---

Уровни по слоям

Слой	DEBUG	INFO	WARNING	ERROR
API	Параметры запроса	Request обработан	—	5xx ошибки
Service	Входные данные	Операция выполнена	Превышен лимит	Ошибка БД
Integration	Raw ответ провайдера	Успешный вызов	Timeout, retry	Внешний API ошибка
Agent	Checksum вычислен	Агент выполнен	Версия не совпала	Ошибка выполнения

---

Правила

• Запрещены f-строки в logger. Только %s (lazy evaluation):

  # ПЛОХО:
  logger.info(f"User {user_id} logged in")
  
  # ХОРОШО:
  logger.info("User %s logged in", user_id)
  

• Структурированные данные передавайте как extra:

  logger.info("Idea analyzed", extra={"idea_id": idea_id, "duration_ms": duration})
  

---

Sensitive Data

Никогда не логировать:

• Пароли (даже хэш)
• JWT токены
• API keys и секреты
• Email в открытом виде (логировать user_id)
• IP адреса полностью (маскировать: 195.208..)

---

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

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s.%(msecs)03dZ %(levelname)s [%(name)s] %(message)s",
    datefmt="%Y-%m-%dT%H:%M:%S",
)

---

[ASK] Вопросы по логированию

• Структурированное логирование (JSON) или текстовое? (JSON — для production)
• Отправлять логи в централизованную систему? (рекомендуется для production)
• Нужен ли audit log для операций с данными? (да, если регуляторные требования)