Шаблон требований к логированию

Логирование нужно для расследования инцидентов, поиска ошибок, сопровождения пользователей и понимания поведения системы в production.

Паспорт документа

Поле	Значение
Система / сервис	`<название>`
Функциональность	`<название>`
Автор	`<ФИО>`
Статус	`Draft / Review / Approved`

Цель логирования

Цель	Описание
Диагностика ошибок	Найти причину ошибки
Трассировка запроса	Проследить путь запроса между сервисами
Контроль интеграций	Видеть ошибки внешних систем
Поддержка пользователей	Найти операцию пользователя по ID

Общие требования

ID	Требование
LOG-001	Каждый входящий запрос должен иметь `correlationId`.
LOG-002	`correlationId` передается во все исходящие вызовы.
LOG-003	В логах не должны храниться пароли, токены, секреты, полные номера карт и другие чувствительные данные.
LOG-004	Ошибки внешних систем логируются с названием системы, кодом ошибки и временем ответа.

Идентификаторы

Идентификатор	Назначение	Кто генерирует
correlationId	Сквозная трассировка бизнес-операции	Первый входной слой / API Gateway / BFF
traceId	Техническая трассировка распределенного вызова	Tracing-инструмент
spanId	Участок trace	Tracing-инструмент
requestId	Конкретный HTTP/gRPC-запрос	Сервис
userId	Пользователь	IAM / auth-сервис

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

Уровень	Когда использовать
TRACE	Детальная диагностика, редко в production
DEBUG	Отладочная информация для dev/test
INFO	Нормальные бизнес- и технические события
WARN	Нестандартная ситуация без падения операции
ERROR	Ошибка, из-за которой операция не выполнена
FATAL	Критическая ошибка приложения

События для логирования

ID	Событие	Уровень	Обязательные поля
LOG-EVT-001	Получен входящий запрос	INFO	correlationId, requestId, method, userId
LOG-EVT-002	Операция завершена	INFO	correlationId, operation, durationMs, status
LOG-EVT-003	Ошибка валидации	WARN	correlationId, field, errorCode
LOG-EVT-004	Исходящий вызов	INFO	correlationId, targetSystem, operation
LOG-EVT-005	Ошибка внешней системы	ERROR	correlationId, targetSystem, statusCode, errorCode
LOG-EVT-006	Retry	WARN	correlationId, attempt, maxAttempts
LOG-EVT-007	Timeout	ERROR	correlationId, timeoutMs, durationMs

Структура JSON-лога

{
  "timestamp": "2026-05-09T12:00:00.000Z",
  "level": "INFO",
  "service": "example-service",
  "environment": "prod",
  "correlationId": "c7b8e7d2-9c1f-4c5a-bc6d-6b4e2d7a0001",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "requestId": "req-123",
  "userId": "user-123",
  "operation": "CreateRequest",
  "message": "Operation completed",
  "durationMs": 153,
  "result": "SUCCESS"
}

Что запрещено логировать

Категория	Примеры
Пароли	password, oldPassword, newPassword
Токены	access token, refresh token
Секреты	api key, private key, secret
Платежные данные	полный номер карты, CVV
ПДн без маскирования	паспорт, телефон, email, адрес

Маскирование

Данные	Как маскировать
Телефон	`+7******1234`
Email	`i***@domain.ru`
Номер карты	`** ** 1234`
Token	`<masked>`

Критерии приемки

ID	Критерий
AC-LOG-001	По `correlationId` можно найти все логи одной операции.
AC-LOG-002	При ошибке зависимости есть `targetSystem`, `errorCode`, `durationMs`.
AC-LOG-003	В логах отсутствуют токены, пароли и секреты.

Открытые вопросы

ID	Вопрос	Кому адресован	Статус
Q-001	`<вопрос>`	`<роль / ФИО>`	Открыт

Критерии приемки документа

ID	Критерий
AC-DOC-001	Документ согласован с владельцем продукта / архитектором / разработкой, если применимо.
AC-DOC-002	Все спорные места вынесены в открытые вопросы или зафиксированы как ограничения.
AC-DOC-003	В документе нет неоднозначных формулировок вроде “быстро”, “удобно”, “корректно” без измеримого критерия.

Шаблон маппинга Шаблон ADR