# Логирование

---

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

```
[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):
  ```python
  # ПЛОХО:
  logger.info(f"User {user_id} logged in")
  
  # ХОРОШО:
  logger.info("User %s logged in", user_id)
  ```

- **Структурированные данные** передавайте как extra:
  ```python
  logger.info("Idea analyzed", extra={"idea_id": idea_id, "duration_ms": duration})
  ```

---

## Sensitive Data

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

---

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

```python
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 для операций с данными? (да, если регуляторные требования)