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

+75
View File
@@ -0,0 +1,75 @@
# Введение
## Зачем нужно логирование
### Цель
Логирование — это ключевой инструмент диагностики и анализа поведения системы. Оно фиксирует
**действия, ошибки и события**, позволяя:
- анализировать поведение приложения;
- находить причины ошибок и сбоев;
- отслеживать бизнес-процессы (например, запуск аудита бренда или генерацию JSON-LD);
- проводить аудит действий пользователей;
- контролировать производительность и стабильность работы.
Хорошее логирование даёт **контекст и доказательства** — кто, когда и что сделал, с каким
результатом.
### Основные задачи логирования
Логирование решает как **технические**, так и **организационные** задачи.
**Технические:**
- **Диагностика:** восстановление хода событий при сбое.
- **Аналитика:** понимание того, как система используется.
- **Поддержка:** ускорение поиска причин ошибок в эксплуатации.
**Организационные:**
- **Аудит:** фиксация действий пользователей и администраторов.
- **Безопасность:** выявление попыток несанкционированного доступа.
## Уровни логирования
В системе используется библиотека **Pino**, интегрированная через `nestjs-pino`. Она поддерживает
стандартные уровни логирования, отражающие важность события.
| Уровень | Метод | Когда использовать | Пример |
| --------- | --------- | --------------------------------------------------- | -------------------------------- |
| **TRACE** | `trace()` | Максимальная детализация, пошаговая трассировка | Проверка цепочки вызовов |
| **DEBUG** | `debug()` | Отладочная информация о логике работы | Вывод промежуточных данных |
| **INFO** | `log()` | Обычные события нормальной работы | Бренд создан |
| **WARN** | `warn()` | Нежелательные, но некритичные ситуации | Отказ в доступе |
| **ERROR** | `error()` | Ошибки, требующие внимания и реакции | Исключение при сохранении |
| **FATAL** | `fatal()` | Критические сбои, приводящие к остановке приложения | Потеря соединения с базой данных |
> 💡 Все уровни логов фиксируются одинаково по структуре данных — различается только их
> **важность**.
## Различие между dev и prod
Логирование настроено так, чтобы быть **удобным в разработке** и **эффективным в продакшене**.
| Среда | Формат | Уровень по умолчанию | Особенности |
| --------------- | ----------------- | -------------------- | --------------------------------------------------------------------- |
| **Development** | человеко-читаемый | `debug` | Цвета, отступы, подробные данные — удобно для чтения в консоли. |
| **Production** | JSON | `info` | Машиночитаемый формат для централизованной агрегации и анализа логов. |
> Состав данных в логе всегда одинаков — меняется только способ отображения. Уровень логирования
> можно переопределить через переменные окружения.
Таким образом:
- в **разработке** акцент на удобство восприятия и диагностику;
- в **продакшене** — на структурированные данные и интеграцию с системами мониторинга (например,
Loki или ELK).
## Где живёт настройка
- `apps/api/src/logger/base.ts` — единственный экземпляр pino, выбор уровня и формата вывода;
- `apps/api/src/logger/logger.class.ts` — класс `Logger`, через который логирует код приложения;
- `apps/api/src/logger/logger.module.ts` — модуль `LocalLoggerModule`: HTTP-логи (`pino-http`) в
`forRoot()` и подмена логгера Nest в `setup()`;
- `apps/api/src/logger/testing/` — логгер для тестов, `LocalLoggerModule.forTesting()`.