# Observability: требования

Observability = логи + трейсы + метрики. Поддержка обязательна во всех сервисах по умолчанию.

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

Правила:
- Структурированные логи (JSON или key=value).
- Уровни: DEBUG/INFO/WARN/ERROR по назначению.
- Нельзя логировать секреты и чувствительные данные.
- Корреляция: `trace_id` обязателен; `span_id` желательно; `request_id`/`message_id` по ситуации.

Практика:
- Вход (HTTP/gRPC/queue) логировать в middleware/interceptor.
- Бизнес-логика логирует только реально исключительные ситуации (без шума/дублирования).
- Ошибки должны иметь контекст (operation/entity_id/cause и т.п.).

## Трассировки (OpenTelemetry + Jaeger)

Правила:
- Любая входящая операция (HTTP/gRPC/queue) создаёт/продолжает trace.
- Контекст трассировки прокидывается между сервисами.
- Внешние вызовы (DB/gRPC/HTTP/queue) — отдельные спаны.
- Внутренний gRPC-сервер должен подключать OpenTelemetry через общий `libs/go/grpcserver`, а не локальными gRPC-перехватчиками в каждом сервисе.
- Для gRPC используется W3C-проброс `tracecontext+baggage`; сервис может подменить `TracerProvider`, `MeterProvider` или propagator только через зависимости общего runtime.

Практика:
- Имена спанов: HTTP `HTTP <method> <route>`; gRPC `<Service>/<Method>`; DB — имя repo-метода (пример: `DB messages.ListRecent(limit=50)`).
- Атрибуты: `http.*`, `rpc.*`, `db.*`, `messaging.*` (семантические конвенции).
- Sampling управляется окружением (dev может быть 100%, prod — выборочно).

## Метрики (Prometheus)

Правила:
- Каждый сервис отдаёт `/metrics`.
- Минимум: операции, ошибки, длительность (histogram), runtime метрики.
- Лейблы ограничивать (избегать высокой кардинальности).

Практика:
- Единый нейминг метрик/лейблов.
- Бизнес-метрики добавлять там, где это помогает продукту/эксплуатации.
- По возможности использовать exemplars для связки “метрики -> трейсы”.
