Files
it-smi/docs/55-logging/02-using.md
T
arswarog bd6f349dc4 api: логирование через pino
Логгер на pino + nestjs-pino вместо стандартного ConsoleLogger: уровни
trace…fatal, details объектом, человекочитаемый вывод в dev и JSON в
проде,
автоматические HTTP-логи (reqId, url, statusCode, responseTime). Для
тестов —
LocalLoggerModule.forTesting() со своим TestingLogger и матчерами.

Документация по логированию — в docs/55-logging.
2026-10-27 10:44:15 +03:00

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');

Правила именования контекста

Хорошие контексты делают логи самодокументируемыми. Чтобы они оставались единообразными, следуйте правилам:

  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().
  • Уровень логирования соответствует окружению.
  • Логи не содержат чувствительных данных.