api: логирование через pino

Логгер на pino + nestjs-pino вместо стандартного ConsoleLogger: уровни
trace…fatal, details объектом, человекочитаемый вывод в dev и JSON в
проде,
автоматические HTTP-логи (reqId, url, statusCode, responseTime). Для
тестов —
LocalLoggerModule.forTesting() со своим TestingLogger и матчерами.

Документация по логированию — в docs/55-logging.
This commit is contained in:
arswarog committed 2026-10-27 10:44:15 +03:00
1 parent 157d79932a
commit bd6f349dc4
21 files changed
+1992 -11

No files matched your search

+68
View File
@@ -0,0 +1,68 @@
# Автоматическое логирование
Автоматическое логирование фиксирует системные события **без участия разработчика**. Оно
обеспечивает единый формат сообщений и полное покрытие ключевых операций платформы.
> 💡 Автоматические логи всегда присутствуют и формируются системой независимо от действий
> разработчика.
## 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-запросы.
- При анализе проблем **начинайте с автоматических логов** — они формируются всегда и имеют единый
формат.