Логгер на pino + nestjs-pino вместо стандартного ConsoleLogger: уровни trace…fatal, details объектом, человекочитаемый вывод в dev и JSON в проде, автоматические HTTP-логи (reqId, url, statusCode, responseTime). Для тестов — LocalLoggerModule.forTesting() со своим TestingLogger и матчерами. Документация по логированию — в docs/55-logging.
4.1 KiB
Автоматическое логирование
Автоматическое логирование фиксирует системные события без участия разработчика. Оно обеспечивает единый формат сообщений и полное покрытие ключевых операций платформы.
💡 Автоматические логи всегда присутствуют и формируются системой независимо от действий разработчика.
HTTP-запросы
Общие принципы
- Каждый HTTP-запрос логируется после завершения обработки.
- Лог формирует middleware
pino-http, который подключается вLocalLoggerModule.forRoot()(apps/api/src/logger/logger.module.ts). - Разработчику не нужно добавлять логи вручную — они создаются автоматически.
Каждая запись содержит:
- HTTP-метод (
GET,POST,PATCHи т. д.); - путь запроса (
/api/...); - код ответа (
200,403,500и т. д.); - время выполнения в миллисекундах (
responseTime); - идентификатор запроса (
reqId); - контекст
HTTP— по нему HTTP-логи отличаются от логов приложения.
Уровни логирования
| Категория ответа | Пример кода | Уровень |
|---|---|---|
| Успешный ответ | 2xx |
info |
| Ошибка клиента | 4xx |
info |
| Ошибка сервера | 5xx |
error |
| Редирект | 3xx |
silent |
Уровень
warnдля HTTP-логов не используется — это предотвращает появление ложных предупреждений при корректных отказах.
Что не попадает в HTTP-логи
Middleware смонтирован на /api/*, поэтому есть два исключения:
- запрос ровно на
/api(без слеша после префикса) — шаблон/api/*его не матчит; - всё, что обслуживает Swagger:
SwaggerModule.setupрегистрирует свои обработчики на Express раньше middlewarepino-http, поэтому/api/docsи его статика в лог не попадают.
Всё остальное, включая 404 по неизвестным путям, логируется.
Задачи HTTP-логов
- Отслеживание активности API.
- Измерение времени обработки запросов.
- Анализ причин ошибок и неудачных вызовов.
- Связь действий пользователей с конкретными маршрутами.
Проверки доступа и исключения
Логирование проверок доступа (RBAC) и необработанных исключений появится вместе с модулями, которые эти события порождают. До этого момента такие события в лог не попадают, и ручные логи в местах отказа — единственный способ их зафиксировать.
Рекомендации
- Не дублируйте автоматические логи вручную.
- Если требуется зафиксировать дополнительный контекст, добавляйте отдельный лог рядом с бизнес-событием — но не повторяйте уже зарегистрированные HTTP-запросы.
- При анализе проблем начинайте с автоматических логов — они формируются всегда и имеют единый формат.