Перейти к основному содержимому

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

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

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

Назначение​

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

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

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

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

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

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

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

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

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

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

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

  • Project created
  • Contest launched
  • Review assigned
  • Evaluation completed

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

  • Project update failed
  • File upload failed
  • Review submission failed

Неправильные формулировки:

  • Creating project... — отражает процесс, а не факт.
  • Contest ${id} launched — содержит шаблон и динамику.
  • Project created successfully! — избыточно и разговорно.

Дополнительные данные​

Контекст события передаётся отдельным объектом (details). Включайте только данные, которые действительно помогают при анализе.

Рекомендации:

  • Всегда указывайте идентификаторы (project, contest, user и т. д.).
  • В идентификаторах избегайте суфиксов id (пример: project вместо projectId).
  • Добавляйте причину (reason) при ошибках или отказах.
  • Указывайте новое состояние (status, result) при изменениях.
  • Не включайте чувствительные данные — токены, e-mail, пароли, персональные сведения.

Пример:

logger.log('Project created', { project: 42, user: 7 });
logger.error('Project update failed', { project: 42, reason: 'invalid_status' });

Бизнес-события​

Что считается бизнес-событием​

Бизнес-события описывают действия и изменения на уровне предметной области, например:

  • Contest launched — запуск конкурса;
  • Project submitted — заявка подана;
  • Review assigned — эксперт назначен;
  • Evaluation completed — оценка завершена.

Все бизнес-события логируются на уровне info (logger.log()), а ошибки бизнес-операций — на уровне error.

Длительные процессы​

Для долгих операций допускается логирование двух фаз:

  • начало — <Action> started;
  • завершение — <Action> (применяется обычные правила оформления сообщений).

Пример:

logger.log('File export started', { contest: 3 });
logger.log('File exported', { contest: 3, durationMs: 14250 });
logger.error('File export failed', { contest: 3, reason: 'timeout' });

Такой подход позволяет отслеживать прогресс и измерять длительность операций.

Зачем нужны бизнес-события​

  • Повышают прозрачность бизнес-процессов.
  • Используются при анализе и аудите.
  • Позволяют отследить жизненный цикл сущностей — от создания до завершения.
  • Упрощают поиск причин ошибок на уровне сценариев пользователей.

Чек-лист перед ревью​

  • Контекст логгера задан.
  • Сообщение короткое, на английском и в прошедшем времени.
  • В details указаны идентификаторы и причина (если применимо).
  • Уровень логирования выбран корректно (info или error).
  • Лог не дублирует автоматические записи (HTTP, RBAC).
  • Отсутствуют конфиденциальные данные.