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:
1 parent
157d79932a
commit
bd6f349dc4
21 files changed
+1992
-11
No files matched your search
@@ -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).
|
||||
- [ ] Отсутствуют конфиденциальные данные.
|
||||
Reference in new issue
Block a user