Логгер на pino + nestjs-pino вместо стандартного ConsoleLogger: уровни trace…fatal, details объектом, человекочитаемый вывод в dev и JSON в проде, автоматические HTTP-логи (reqId, url, statusCode, responseTime). Для тестов — LocalLoggerModule.forTesting() со своим TestingLogger и матчерами. Документация по логированию — в docs/55-logging.
7.4 KiB
Ручное логирование и бизнес-события
Автоматическое логирование фиксирует системные события (HTTP-запросы, ошибки), но не отражает внутреннюю бизнес-логику приложения.
Ручное логирование используется для фиксации действий и изменений, важных с точки зрения продукта — того, что видит или делает пользователь.
Назначение
Ручные логи применяются для описания событий, которые отражают состояние системы и бизнес-процессы:
- создание, изменение и удаление сущностей;
- начало и завершение процессов;
- изменение статуса или состояния;
- ошибки бизнес-операций;
- любые другие действия, значимые для анализа и аудита.
Такое логирование помогает понять, что происходило внутри системы, даже без включённой отладки или доступа к базе данных.
Правила оформления логов
Общие принципы
Сообщения должны быть:
- краткими — не длиннее одной фразы;
- человеко-читаемыми — понятными без знания кода;
- однозначными — описывать факт, а не процесс;
- на английском, в прошедшем времени, без артиклей и пунктуации.
Если операция завершилась неудачей, сообщение должно оканчиваться на failed.
Логирование выполняется после завершения операции — независимо от результата.
Примеры сообщений
Успешные операции:
Brand createdPassport filledJsonLd generatedAudit completed
Ошибки и неудачи:
Brand update failedFile upload failedJsonLd generation failed
Неправильные формулировки:
Creating brand...— отражает процесс, а не факт.Brand ${id} created— содержит шаблон и динамику.Brand created successfully!— избыточно и разговорно.
Дополнительные данные
Контекст события передаётся отдельным объектом (details). Включайте только данные, которые
действительно помогают при анализе.
Рекомендации:
- Всегда указывайте идентификаторы (
brand,audit,userи т. д.). - В идентификаторах избегайте суфиксов
id(пример:brandвместоbrandId). - Добавляйте причину (
reason) при ошибках или отказах. - Указывайте новое состояние (
status,result) при изменениях. - Не включайте чувствительные данные — токены, e-mail, пароли, персональные сведения.
details передаются вторым аргументом на всех уровнях: trace, debug, log, warn, error,
fatal. Логгер сам раскладывает объект в поля JSON-записи, поэтому сериализовать его в строку не
нужно — наоборот, строка в details попадёт в лог как текст и потеряет структуру.
Пример:
logger.log('Brand created', { brand: 42, user: 7 });
logger.error('Brand update failed', { brand: 42, reason: 'invalid_status' });
Ошибку со стеком можно передать третьим аргументом — тогда он попадёт в лог как trace:
logger.error('JsonLd generation failed', error.stack, { brand: 42 });
Как объект попадает в запись
Сигнатура LoggerService в Nest описывает error(message, stack, context), а
log(message, ...optionalParams) — без отдельного места под объект. Наш Logger
(logger.class.ts) приводит вызов к форме pino: logger[level](details, message). Поэтому:
details— обычный объект, не JSON-строка;- для
error()второй аргумент со строковым стеком уезжает в полеtrace, а объектdetailsможно передать вторым или третьим аргументом.
Бизнес-события
Что считается бизнес-событием
Бизнес-события описывают действия и изменения на уровне предметной области, например:
Brand created— бренд заведён;Passport filled— паспорт бренда заполнен;JsonLd exported— структурированные данные выгружены;Audit completed— NAP-аудит завершён.
Все бизнес-события логируются на уровне
info(logger.log()), а ошибки бизнес-операций — на уровнеerror.
Длительные процессы
Для долгих операций допускается логирование двух фаз:
- начало —
<Action> started; - завершение —
<Action>(применяются обычные правила оформления сообщений).
Пример:
logger.log('JsonLd export started', { brand: 3 });
logger.log('JsonLd exported', { brand: 3, durationMs: 14250 });
logger.error('JsonLd export failed', { brand: 3, reason: 'timeout' });
Такой подход позволяет отслеживать прогресс и измерять длительность операций.
Зачем нужны бизнес-события
- Повышают прозрачность бизнес-процессов.
- Используются при анализе и аудите.
- Позволяют отследить жизненный цикл сущностей — от создания до завершения.
- Упрощают поиск причин ошибок на уровне сценариев пользователей.
Чек-лист перед ревью
- Контекст логгера задан.
- Сообщение короткое, на английском и в прошедшем времени.
- В
detailsуказаны идентификаторы и причина (если применимо). - Уровень логирования выбран корректно (
infoилиerror). - Лог не дублирует автоматические записи (HTTP).
- Отсутствуют конфиденциальные данные.