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,103 @@
|
||||
# Подключение и использование
|
||||
|
||||
## Получение логгера
|
||||
|
||||
Логгер внедряется в любой сервис, контроллер или компонент через **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()`.
|
||||
- [ ] Уровень логирования соответствует окружению.
|
||||
- [ ] Логи не содержат чувствительных данных.
|
||||
Reference in new issue
Block a user