Логгер на pino + nestjs-pino вместо стандартного ConsoleLogger: уровни trace…fatal, details объектом, человекочитаемый вывод в dev и JSON в проде, автоматические HTTP-логи (reqId, url, statusCode, responseTime). Для тестов — LocalLoggerModule.forTesting() со своим TestingLogger и матчерами. Документация по логированию — в docs/55-logging.
104 lines
5.7 KiB
Markdown
104 lines
5.7 KiB
Markdown
# Подключение и использование
|
|
|
|
## Получение логгера
|
|
|
|
Логгер внедряется в любой сервис, контроллер или компонент через **dependency injection**. После
|
|
внедрения требуется указать **контекст**, чтобы логи было проще анализировать.
|
|
|
|
```ts
|
|
@Injectable()
|
|
export class BrandService {
|
|
constructor(private readonly logger: Logger) {
|
|
this.logger.setContext('Brands');
|
|
}
|
|
|
|
async createBrand(data: CreateBrandDto) {
|
|
this.logger.log('Brand created', { brand: 42, user: data.ownerId });
|
|
}
|
|
}
|
|
```
|
|
|
|
Модуль, в котором объявлен сервис, должен импортировать `LocalLoggerModule.forRoot()` (он помечен
|
|
`global: true`, поэтому достаточно один раз в `AppModule`).
|
|
|
|
## Контекст логгера
|
|
|
|
Контекст указывает, **к какому модулю или бизнес-процессу относится лог**. Он помогает группировать
|
|
события и быстрее понимать источник при анализе системы.
|
|
|
|
Контекст задаётся вручную при инициализации логгера:
|
|
|
|
```ts
|
|
constructor(private readonly logger: Logger) {
|
|
this.logger.setContext('Evaluation');
|
|
}
|
|
```
|
|
|
|
Вне DI (в `main.ts`, в bootstrap-сценариях) логгер создаётся с контекстом в конструкторе:
|
|
|
|
```ts
|
|
const logger = new Logger('Bootstrap');
|
|
```
|
|
|
|
## Правила именования контекста
|
|
|
|
Хорошие контексты делают логи самодокументируемыми. Чтобы они оставались единообразными, следуйте
|
|
правилам:
|
|
|
|
1. **Основой контекста является название модуля**, отражающее область бизнес-логики. Примеры:
|
|
- `Brands` — работа с карточками брендов;
|
|
- `JsonLd` — генерация структурированных данных;
|
|
- `Users` — работа с пользователями.
|
|
|
|
2. **При необходимости уточнения** добавляется второй уровень через двоеточие:
|
|
- `Brands:Passport` — паспорт бренда;
|
|
- `Audit:History` — журнал изменений.
|
|
|
|
3. **Технические роли** (`Service`, `Controller` и т. п.) в названии **не используются**, так как
|
|
контекст должен отражать **бизнес-смысл**, а не структуру кода.
|
|
|
|
> 💬 Контекст — часть “языка логирования” проекта. Он должен быть **стабильным, понятным и
|
|
> единообразным** во всех модулях.
|
|
|
|
## Контекст запроса
|
|
|
|
При логировании внутри HTTP-запроса `pino-http` автоматически добавляет поля:
|
|
|
|
- `reqId` — идентификатор запроса;
|
|
- `url` — метод и адрес текущего запроса.
|
|
|
|
Это позволяет связывать бизнес-события с конкретными запросами и упрощает анализ логов. Ручные логи
|
|
внутри запроса достаточно писать через инжектированный `Logger` — связывать их с запросом вручную не
|
|
нужно, но и `reqId` в `details` дублировать не следует.
|
|
|
|
## Переменные окружения
|
|
|
|
Настройки логирования задаются через `.env` или переменные окружения.
|
|
|
|
| Переменная | Назначение | Пример значения |
|
|
| ------------ | ------------------------------------------------- | -------------------------------- |
|
|
| `LOG_LEVEL` | Минимальный уровень логирования. | `debug`, `info`, `warn`, `error` |
|
|
| `LOG_PRETTY` | Включает человеко-читаемый формат (обычно в dev). | `true` |
|
|
|
|
Если переменные не заданы, применяются значения по умолчанию:
|
|
|
|
| Окружение | Значения по умолчанию |
|
|
| --------- | ------------------------------------ |
|
|
| **dev** | `LOG_LEVEL=debug`, `LOG_PRETTY=true` |
|
|
| **prod** | `LOG_LEVEL=info`, `LOG_PRETTY=false` |
|
|
|
|
Прод определяется как `NODE_ENV=production` (в образе api это значение выставлено в `Dockerfile`)
|
|
или явным `LOG_PRETTY=false`. Образ api ставит только production-зависимости, а `pino-pretty` —
|
|
dev-зависимость: если запустить контейнер без `NODE_ENV=production`, воркер pretty-транспорта не
|
|
найдётся.
|
|
|
|
> 🔧 Уровень логирования можно переопределить без релиза — через переменные окружения при запуске
|
|
> приложения.
|
|
|
|
## Чек-лист перед ревью
|
|
|
|
- [ ] Логгер подключён через dependency injection.
|
|
- [ ] Контекст задан явно через `setContext()`.
|
|
- [ ] Уровень логирования соответствует окружению.
|
|
- [ ] Логи не содержат чувствительных данных.
|