# Ручное логирование и бизнес-события Автоматическое логирование фиксирует системные события (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` попадёт в лог как текст и потеряет структуру. **Пример:** ```ts logger.log('Brand created', { brand: 42, user: 7 }); logger.error('Brand update failed', { brand: 42, reason: 'invalid_status' }); ``` Ошибку со стеком можно передать третьим аргументом — тогда он попадёт в лог как `trace`: ```ts 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`. ### Длительные процессы Для долгих операций допускается логирование **двух фаз**: - начало — ` started`; - завершение — `` (применяются обычные правила оформления сообщений). **Пример:** ```ts 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). - [ ] Отсутствуют конфиденциальные данные.