← [Раздел](README.md) · [Главная](../README.md)

# Логирование в облачных приложениях

## Цель

Научиться проектировать **структурированные логи**: что писать, чего избегать, как уровни и поля помогают в инцидентах, и как не превратить лог-хранилище в свалку PII и секретов.

## Предварительно

- [README раздела 08](README.md)
- Опыт с `console.log` / `print` в любом языке

## Время

~50 минут

---

## Зачем логи в production

Лог — **событие с контекстом** в момент времени. Используется для:

- расследования инцидентов;
- аудита действий (кто удалил заказ);
- отладки редких багов без воспроизведения;
- корреляции с метриками и трейсами.

Логи **не заменяют** метрики (агрегация дорогая) и **не заменяют** трейсы (нет полной картины latency по span).

---

## Структурированный vs текстовый

| Подход | Пример | Плюсы |
|--------|--------|-------|
| Текст | `User 42 failed login` | Читаемо глазами |
| JSON | `{"event":"login_failed","user_id":42}` | Поиск, фильтры, парсинг |

В облаке предпочтителен **JSON** (или key-value) с фиксированным набором полей.

### Рекомендуемые поля

| Поле | Описание |
|------|----------|
| `timestamp` | ISO 8601, UTC |
| `level` | debug, info, warn, error |
| `message` | Краткое описание |
| `service` | `order-api` |
| `trace_id` / `request_id` | Склейка с трейсом |
| `user_id` | Если есть (без PII лишнего) |
| `error` | Тип и сообщение (не весь stack в info) |

---

## Уровни логирования

| Уровень | Когда | Production |
|---------|-------|------------|
| **DEBUG** | Детали для разработки | Обычно выключен |
| **INFO** | Штатные события (заказ создан) | Да, умеренно |
| **WARN** | Странно, но обработали (retry) | Да |
| **ERROR** | Операция не удалась | Да + алерт по rate |

**Правило:** один лог на одно **бизнес-событие** или одну **ошибку** — не спамьте на каждую строку цикла.

---

## Что логировать на критичном пути

Для `POST /orders`:

```json
{
  "level": "info",
  "event": "order_created",
  "order_id": "ord_8f2a",
  "user_id": "usr_100",
  "amount_cents": 4990,
  "request_id": "7f3c2a1b-4e5d-6f7a-8b9c-0d1e2f3a4b5c",
  "duration_ms": 124
}
```

При ошибке оплаты:

```json
{
  "level": "error",
  "event": "payment_failed",
  "order_id": "ord_8f2a",
  "payment_provider": "example-pay",
  "error_code": "CARD_DECLINED",
  "request_id": "7f3c2a1b-..."
}
```

---

## Чего НЕ логировать

| Запрещено | Причина |
|-----------|---------|
| Пароли, OTP, полные токены | Утечка через log store |
| Номера карт, CVV | PCI |
| Полный JWT | Replay при компрометации логов |
| Паспортные данные без нужды | GDPR / 152-ФЗ |

Маскируйте: `card_last4`, `email_hash`, `token_prefix=eyJhbG...`.

---

## Централизация и retention

```text
Pod A ─┐
Pod B ─┼→ collector (Fluent Bit) → хранилище → поиск (Grafana/Loki)
Pod C ─┘
```

| Решение | Ориентир |
|---------|----------|
| **Retention hot** | 7–30 дней для отладки |
| **Retention cold** | 90–365 дней для аудита (отдельный индекс) |
| **Сэмплиринг** | DEBUG-трафик — 1% на высоком RPS |

Логи стоят денег. Согласуйте объём с SRE: **индексируйте** важные поля, не весь мегабайтный payload.

---

## Логи и безопасность

- Доступ к production-логам — по RBAC (не всем разработчикам).
- Audit log (смена ролей, удаление данных) — **отдельный поток**, append-only.
- При инциденте безопасности — процедура изъятия логов без уничтожения доказательств.

---

## Антипаттерны

| Плохо | Лучше |
|-------|-------|
| `console.log` без структуры | Logger с JSON и уровнями |
| Логировать тело запроса целиком | Whitelist полей |
| Один гигантский файл на VM | stdout → collector (12-factor) |
| Разный формат в каждом сервисе | Общая библиотека / schema |

---

## Связь с трейсами

Добавляйте `trace_id` из OpenTelemetry в каждую запись — в UI можно перейти от лога к flame graph. Подробнее: [tracing-i-alerty.md](tracing-i-alerty.md).

---

## Самопроверка

1. Чем структурированный лог лучше свободного текста в production?
2. Какие пять полей вы бы сделали обязательными?
3. Назовите три типа данных, которые нельзя писать в лог.
4. Зачем разный retention для debug и audit?

---

## Дальше

→ [Метрики и SLO](metriki-i-slo.md)  
← [README раздела 08](README.md)