api: логирование через pino

Логгер на pino + nestjs-pino вместо стандартного ConsoleLogger: уровни
trace…fatal, details объектом, человекочитаемый вывод в dev и JSON в
проде,
автоматические HTTP-логи (reqId, url, statusCode, responseTime). Для
тестов —
LocalLoggerModule.forTesting() со своим TestingLogger и матчерами.

Документация по логированию — в docs/55-logging.
This commit is contained in:
arswarog committed 2026-10-27 10:44:15 +03:00
1 parent 157d79932a
commit bd6f349dc4
21 files changed
+1992 -11

No files matched your search

+143
View File
@@ -0,0 +1,143 @@
# Ручное логирование и бизнес-события
Автоматическое логирование фиксирует системные события (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`.
### Длительные процессы
Для долгих операций допускается логирование **двух фаз**:
- начало — `<Action> started`;
- завершение — `<Action>` (применяются обычные правила оформления сообщений).
**Пример:**
```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).
- [ ] Отсутствуют конфиденциальные данные.