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