Files
it-smi/docs/55-logging/03-auto-logging.md
T
arswarog bd6f349dc4 api: логирование через pino
Логгер на pino + nestjs-pino вместо стандартного ConsoleLogger: уровни
trace…fatal, details объектом, человекочитаемый вывод в dev и JSON в
проде,
автоматические HTTP-логи (reqId, url, statusCode, responseTime). Для
тестов —
LocalLoggerModule.forTesting() со своим TestingLogger и матчерами.

Документация по логированию — в docs/55-logging.
2026-10-27 10:44:15 +03:00

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 раньше middleware pino-http, поэтому /api/docs и его статика в лог не попадают.

Всё остальное, включая 404 по неизвестным путям, логируется.

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

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

Проверки доступа и исключения

Логирование проверок доступа (RBAC) и необработанных исключений появится вместе с модулями, которые эти события порождают. До этого момента такие события в лог не попадают, и ручные логи в местах отказа — единственный способ их зафиксировать.

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

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