Логгер на pino + nestjs-pino вместо стандартного ConsoleLogger: уровни trace…fatal, details объектом, человекочитаемый вывод в dev и JSON в проде, автоматические HTTP-логи (reqId, url, statusCode, responseTime). Для тестов — LocalLoggerModule.forTesting() со своим TestingLogger и матчерами. Документация по логированию — в docs/55-logging.
5.7 KiB
Подключение и использование
Получение логгера
Логгер внедряется в любой сервис, контроллер или компонент через dependency injection. После внедрения требуется указать контекст, чтобы логи было проще анализировать.
@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).
Контекст логгера
Контекст указывает, к какому модулю или бизнес-процессу относится лог. Он помогает группировать события и быстрее понимать источник при анализе системы.
Контекст задаётся вручную при инициализации логгера:
constructor(private readonly logger: Logger) {
this.logger.setContext('Evaluation');
}
Вне DI (в main.ts, в bootstrap-сценариях) логгер создаётся с контекстом в конструкторе:
const logger = new Logger('Bootstrap');
Правила именования контекста
Хорошие контексты делают логи самодокументируемыми. Чтобы они оставались единообразными, следуйте правилам:
-
Основой контекста является название модуля, отражающее область бизнес-логики. Примеры:
Brands— работа с карточками брендов;JsonLd— генерация структурированных данных;Users— работа с пользователями.
-
При необходимости уточнения добавляется второй уровень через двоеточие:
Brands:Passport— паспорт бренда;Audit:History— журнал изменений.
-
Технические роли (
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(). - Уровень логирования соответствует окружению.
- Логи не содержат чувствительных данных.