Автоматическое логирование

Автоматическое логирование фиксирует системные события без участия разработчика. Оно обеспечивает единый формат сообщений и полное покрытие ключевых операций платформы — HTTP-запросов, проверок доступа (RBAC) и ошибок.

Назначение

Цели автоматического логирования:

• Сократить количество ручных логов в коде.
• Обеспечить единообразие сообщений и уровней логирования.
• Повысить наблюдаемость и удобство диагностики.
• Позволить анализировать производительность и отказы без изменения бизнес-логики.

💡 Автоматические логи всегда присутствуют и формируются системой независимо от действий разработчика.

Источники автоматических логов

Тип события	Источник	Что логируется
HTTP-запросы	middleware pino-http	Каждый завершённый запрос с кодом ответа и временем обработки.
Проверки доступа (RBAC)	модуль RbacModule	Успешные и неуспешные проверки разрешений.
Ошибки и исключения	глобальный ExceptionFilter	Необработанные ошибки приложения и системные сбои.

Все эти события регистрируются автоматически и не требуют дополнительного кода в модулях.

HTTP-запросы

Общие принципы

• Каждый HTTP-запрос логируется после завершения обработки.
• Лог формируется middleware pino-http на основе данных ответа.
• Разработчику не нужно добавлять логи вручную — они создаются автоматически.

Каждая запись содержит:

• HTTP-метод (GET, POST, PATCH и т. д.);
• путь запроса (/api/v1/...);
• код ответа (200, 403, 500 и т. д.);
• время выполнения (в миллисекундах);
• идентификатор пользователя (user, если известен).

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

Категория ответа	Пример кода	Уровень
Успешный ответ	2xx	info
Ошибка клиента	4xx	info
Ошибка сервера	5xx	error

Уровень warn для HTTP-логов не используется — это предотвращает появление ложных предупреждений при корректных отказах.

Задачи HTTP-логов

• Отслеживание активности API.
• Измерение времени обработки запросов.
• Анализ причин ошибок и неудачных вызовов.
• Связь действий пользователей с конкретными маршрутами.

Проверки доступа (RBAC)

Общие принципы

Все проверки доступа логируются автоматически при вызовах методов check* и accessDenied. Это обеспечивает аудит всех случаев — и разрешённых, и запрещённых действий.

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

Событие	Уровень	Что фиксируется
Отказ в доступе	warn	Попытка выполнить действие без нужного разрешения.
Доступ разрешён	debug	Успешная проверка разрешения.

Такое распределение уровней помогает разделять реальные проблемы (отказы) и штатные сценарии (успешные проверки).

Ошибки и исключения

Общие принципы

Глобальный ExceptionFilter автоматически логирует все необработанные ошибки:

• error — ошибки приложения (например, неверные данные или сбой бизнес-логики);
• fatal — критические сбои, приводящие к остановке приложения (например, невозможность подключиться к базе данных).

Структура записи

Каждая запись об ошибке включает:

• trace — стек вызовов;
• context — модуль, где произошла ошибка;
• user и url — если ошибка возникла в контексте HTTP-запроса.

Это обеспечивает точную локализацию проблем и упрощает разбор инцидентов.

Рекомендации

• Не дублируйте автоматические логи вручную.
• Если требуется зафиксировать дополнительный контекст, добавляйте отдельный лог рядом с бизнес-событием — но не повторяйте уже зарегистрированные HTTP-запросы или проверки доступа.
• При анализе проблем начинайте с автоматических логов — они формируются всегда и имеют единый формат.