Files
it-smi/docs/55-logging/04-manual-logs.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

7.4 KiB

Ручное логирование и бизнес-события

Автоматическое логирование фиксирует системные события (HTTP-запросы, ошибки), но не отражает внутреннюю бизнес-логику приложения.

Ручное логирование используется для фиксации действий и изменений, важных с точки зрения продукта — того, что видит или делает пользователь.

Назначение

Ручные логи применяются для описания событий, которые отражают состояние системы и бизнес-процессы:

  • создание, изменение и удаление сущностей;
  • начало и завершение процессов;
  • изменение статуса или состояния;
  • ошибки бизнес-операций;
  • любые другие действия, значимые для анализа и аудита.

Такое логирование помогает понять, что происходило внутри системы, даже без включённой отладки или доступа к базе данных.

Правила оформления логов

Общие принципы

Сообщения должны быть:

  • краткими — не длиннее одной фразы;
  • человеко-читаемыми — понятными без знания кода;
  • однозначными — описывать факт, а не процесс;
  • на английском, в прошедшем времени, без артиклей и пунктуации.

Если операция завершилась неудачей, сообщение должно оканчиваться на failed.

Логирование выполняется после завершения операции — независимо от результата.

Примеры сообщений

Успешные операции:

  • Brand created
  • Passport filled
  • JsonLd generated
  • Audit completed

Ошибки и неудачи:

  • Brand update failed
  • File upload failed
  • JsonLd 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).
  • Отсутствуют конфиденциальные данные.