docs: simplify conventions layout

2026-09-15 05:58:33 +03:00
parent 9810d47e42
commit 016782657a
13 changed files with 263 additions and 276 deletions
@@ -0,0 +1,24 @@
+# Observability
+
+- Единственный logger — nestjs-pino. Application events используют
+  [StructuredLogger](../../src/common/logging/structured-logger.service.ts),
+  стабильное имя события и разрешённые scalar fields. `console.log` и второй
+  logger в production не используются.
+- `info` — значимый lifecycle/outcome; `debug` — подробности успешного RPC;
+  `warn` — восстановимая проблема/retry; `error` — окончательный сбой.
+  Не добавляй log на каждый вход/выход функции или дубликат HTTP completion.
+- RequestContextService и request middleware владеют correlation: серверный
+  request ID возвращается как `X-Request-ID`, входящий client ID хранится отдельно.
+  Передавай существующий context, не создавай собственный UUID в каждом service.
+- Wrapper ограничивает поля, Pino redacts request secrets. Не логируй passwords,
+  tokens, cookie, Authorization, credentials, connection generation, raw body
+  или upstream error. Secret в `message/stack` не становится безопасным из-за
+  allowlist; правила [Security](security-auth.md) обязательны для sensitive data.
+- Для ошибки используй public code и безопасный context операции/попыток;
+  [error mapping](error-handling.md) не отдаёт внутренние детали клиенту.
+
+Причины — [ADR 008](../../../docs/adr/008-pino-backend-logging.md), системное
+поведение — [HTTP observability](../../../docs/architecture/http-api.md#наблюдаемость).
+Проверяй новые поля/redaction/correlation existing logging tests; не добавляй
+тест на каждую строку log. Existing ESLint не запрещает все вызовы `console`
+отдельным правилом: до настройки встроенного `no-console` это semantic review.