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:
1 parent
157d79932a
commit
bd6f349dc4
21 files changed
+1992
-11
No files matched your search
@@ -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-запросы.
|
||||
- При анализе проблем **начинайте с автоматических логов** — они формируются всегда и имеют единый
|
||||
формат.
|
||||
Reference in new issue
Block a user