Логгер на pino + nestjs-pino вместо стандартного ConsoleLogger: уровни trace…fatal, details объектом, человекочитаемый вывод в dev и JSON в проде, автоматические HTTP-логи (reqId, url, statusCode, responseTime). Для тестов — LocalLoggerModule.forTesting() со своим TestingLogger и матчерами. Документация по логированию — в docs/55-logging.
69 lines
4.1 KiB
Markdown
69 lines
4.1 KiB
Markdown
# Автоматическое логирование
|
|
|
|
Автоматическое логирование фиксирует системные события **без участия разработчика**. Оно
|
|
обеспечивает единый формат сообщений и полное покрытие ключевых операций платформы.
|
|
|
|
> 💡 Автоматические логи всегда присутствуют и формируются системой независимо от действий
|
|
> разработчика.
|
|
|
|
## 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-запросы.
|
|
- При анализе проблем **начинайте с автоматических логов** — они формируются всегда и имеют единый
|
|
формат.
|