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

+75
View File
@@ -0,0 +1,75 @@
# Введение
## Зачем нужно логирование
### Цель
Логирование — это ключевой инструмент диагностики и анализа поведения системы. Оно фиксирует
**действия, ошибки и события**, позволяя:
- анализировать поведение приложения;
- находить причины ошибок и сбоев;
- отслеживать бизнес-процессы (например, запуск аудита бренда или генерацию JSON-LD);
- проводить аудит действий пользователей;
- контролировать производительность и стабильность работы.
Хорошее логирование даёт **контекст и доказательства** — кто, когда и что сделал, с каким
результатом.
### Основные задачи логирования
Логирование решает как **технические**, так и **организационные** задачи.
**Технические:**
- **Диагностика:** восстановление хода событий при сбое.
- **Аналитика:** понимание того, как система используется.
- **Поддержка:** ускорение поиска причин ошибок в эксплуатации.
**Организационные:**
- **Аудит:** фиксация действий пользователей и администраторов.
- **Безопасность:** выявление попыток несанкционированного доступа.
## Уровни логирования
В системе используется библиотека **Pino**, интегрированная через `nestjs-pino`. Она поддерживает
стандартные уровни логирования, отражающие важность события.
| Уровень | Метод | Когда использовать | Пример |
| --------- | --------- | --------------------------------------------------- | -------------------------------- |
| **TRACE** | `trace()` | Максимальная детализация, пошаговая трассировка | Проверка цепочки вызовов |
| **DEBUG** | `debug()` | Отладочная информация о логике работы | Вывод промежуточных данных |
| **INFO** | `log()` | Обычные события нормальной работы | Бренд создан |
| **WARN** | `warn()` | Нежелательные, но некритичные ситуации | Отказ в доступе |
| **ERROR** | `error()` | Ошибки, требующие внимания и реакции | Исключение при сохранении |
| **FATAL** | `fatal()` | Критические сбои, приводящие к остановке приложения | Потеря соединения с базой данных |
> 💡 Все уровни логов фиксируются одинаково по структуре данных — различается только их
> **важность**.
## Различие между dev и prod
Логирование настроено так, чтобы быть **удобным в разработке** и **эффективным в продакшене**.
| Среда | Формат | Уровень по умолчанию | Особенности |
| --------------- | ----------------- | -------------------- | --------------------------------------------------------------------- |
| **Development** | человеко-читаемый | `debug` | Цвета, отступы, подробные данные — удобно для чтения в консоли. |
| **Production** | JSON | `info` | Машиночитаемый формат для централизованной агрегации и анализа логов. |
> Состав данных в логе всегда одинаков — меняется только способ отображения. Уровень логирования
> можно переопределить через переменные окружения.
Таким образом:
- в **разработке** акцент на удобство восприятия и диагностику;
- в **продакшене** — на структурированные данные и интеграцию с системами мониторинга (например,
Loki или ELK).
## Где живёт настройка
- `apps/api/src/logger/base.ts` — единственный экземпляр pino, выбор уровня и формата вывода;
- `apps/api/src/logger/logger.class.ts` — класс `Logger`, через который логирует код приложения;
- `apps/api/src/logger/logger.module.ts` — модуль `LocalLoggerModule`: HTTP-логи (`pino-http`) в
`forRoot()` и подмена логгера Nest в `setup()`;
- `apps/api/src/logger/testing/` — логгер для тестов, `LocalLoggerModule.forTesting()`.
+103
View File
@@ -0,0 +1,103 @@
# Подключение и использование
## Получение логгера
Логгер внедряется в любой сервис, контроллер или компонент через **dependency injection**. После
внедрения требуется указать **контекст**, чтобы логи было проще анализировать.
```ts
@Injectable()
export class BrandService {
constructor(private readonly logger: Logger) {
this.logger.setContext('Brands');
}
async createBrand(data: CreateBrandDto) {
this.logger.log('Brand created', { brand: 42, user: data.ownerId });
}
}
```
Модуль, в котором объявлен сервис, должен импортировать `LocalLoggerModule.forRoot()` (он помечен
`global: true`, поэтому достаточно один раз в `AppModule`).
## Контекст логгера
Контекст указывает, **к какому модулю или бизнес-процессу относится лог**. Он помогает группировать
события и быстрее понимать источник при анализе системы.
Контекст задаётся вручную при инициализации логгера:
```ts
constructor(private readonly logger: Logger) {
this.logger.setContext('Evaluation');
}
```
Вне DI (в `main.ts`, в bootstrap-сценариях) логгер создаётся с контекстом в конструкторе:
```ts
const logger = new Logger('Bootstrap');
```
## Правила именования контекста
Хорошие контексты делают логи самодокументируемыми. Чтобы они оставались единообразными, следуйте
правилам:
1. **Основой контекста является название модуля**, отражающее область бизнес-логики. Примеры:
- `Brands` — работа с карточками брендов;
- `JsonLd` — генерация структурированных данных;
- `Users` — работа с пользователями.
2. **При необходимости уточнения** добавляется второй уровень через двоеточие:
- `Brands:Passport` — паспорт бренда;
- `Audit:History` — журнал изменений.
3. **Технические роли** (`Service`, `Controller` и т. п.) в названии **не используются**, так как
контекст должен отражать **бизнес-смысл**, а не структуру кода.
> 💬 Контекст — часть “языка логирования” проекта. Он должен быть **стабильным, понятным и
> единообразным** во всех модулях.
## Контекст запроса
При логировании внутри HTTP-запроса `pino-http` автоматически добавляет поля:
- `reqId` — идентификатор запроса;
- `url` — метод и адрес текущего запроса.
Это позволяет связывать бизнес-события с конкретными запросами и упрощает анализ логов. Ручные логи
внутри запроса достаточно писать через инжектированный `Logger` — связывать их с запросом вручную не
нужно, но и `reqId` в `details` дублировать не следует.
## Переменные окружения
Настройки логирования задаются через `.env` или переменные окружения.
| Переменная | Назначение | Пример значения |
| ------------ | ------------------------------------------------- | -------------------------------- |
| `LOG_LEVEL` | Минимальный уровень логирования. | `debug`, `info`, `warn`, `error` |
| `LOG_PRETTY` | Включает человеко-читаемый формат (обычно в dev). | `true` |
Если переменные не заданы, применяются значения по умолчанию:
| Окружение | Значения по умолчанию |
| --------- | ------------------------------------ |
| **dev** | `LOG_LEVEL=debug`, `LOG_PRETTY=true` |
| **prod** | `LOG_LEVEL=info`, `LOG_PRETTY=false` |
Прод определяется как `NODE_ENV=production` (в образе api это значение выставлено в `Dockerfile`)
или явным `LOG_PRETTY=false`. Образ api ставит только production-зависимости, а `pino-pretty` —
dev-зависимость: если запустить контейнер без `NODE_ENV=production`, воркер pretty-транспорта не
найдётся.
> 🔧 Уровень логирования можно переопределить без релиза — через переменные окружения при запуске
> приложения.
## Чек-лист перед ревью
- [ ] Логгер подключён через dependency injection.
- [ ] Контекст задан явно через `setContext()`.
- [ ] Уровень логирования соответствует окружению.
- [ ] Логи не содержат чувствительных данных.
+68
View File
@@ -0,0 +1,68 @@
# Автоматическое логирование
Автоматическое логирование фиксирует системные события **без участия разработчика**. Оно
обеспечивает единый формат сообщений и полное покрытие ключевых операций платформы.
> 💡 Автоматические логи всегда присутствуют и формируются системой независимо от действий
> разработчика.
## HTTP-запросы
### Общие принципы
- Каждый HTTP-запрос логируется **после завершения обработки**.
- Лог формирует middleware `pino-http`, который подключается в `LocalLoggerModule.forRoot()`
(`apps/api/src/logger/logger.module.ts`).
- Разработчику не нужно добавлять логи вручную — они создаются автоматически.
Каждая запись содержит:
- HTTP-метод (`GET`, `POST`, `PATCH` и т. д.);
- путь запроса (`/api/...`);
- код ответа (`200`, `403`, `500` и т. д.);
- время выполнения в миллисекундах (`responseTime`);
- идентификатор запроса (`reqId`);
- контекст `HTTP` — по нему HTTP-логи отличаются от логов приложения.
### Уровни логирования
| Категория ответа | Пример кода | Уровень |
| ---------------- | ----------- | -------- |
| Успешный ответ | `2xx` | `info` |
| Ошибка клиента | `4xx` | `info` |
| Ошибка сервера | `5xx` | `error` |
| Редирект | `3xx` | `silent` |
> Уровень `warn` для HTTP-логов не используется — это предотвращает появление ложных предупреждений
> при корректных отказах.
### Что не попадает в HTTP-логи
Middleware смонтирован на `/api/*`, поэтому есть два исключения:
- запрос ровно на `/api` (без слеша после префикса) — шаблон `/api/*` его не матчит;
- всё, что обслуживает Swagger: `SwaggerModule.setup` регистрирует свои обработчики на Express
раньше middleware `pino-http`, поэтому `/api/docs` и его статика в лог не попадают.
Всё остальное, включая 404 по неизвестным путям, логируется.
### Задачи HTTP-логов
- Отслеживание активности API.
- Измерение времени обработки запросов.
- Анализ причин ошибок и неудачных вызовов.
- Связь действий пользователей с конкретными маршрутами.
## Проверки доступа и исключения
Логирование проверок доступа (RBAC) и необработанных исключений появится вместе с модулями, которые
эти события порождают. До этого момента такие события в лог не попадают, и ручные логи в местах
отказа — единственный способ их зафиксировать.
## Рекомендации
- Не дублируйте автоматические логи вручную.
- Если требуется зафиксировать **дополнительный** контекст, добавляйте отдельный лог рядом с
бизнес-событием — но не повторяйте уже зарегистрированные HTTP-запросы.
- При анализе проблем **начинайте с автоматических логов** — они формируются всегда и имеют единый
формат.
+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).
- [ ] Отсутствуют конфиденциальные данные.
+159
View File
@@ -0,0 +1,159 @@
# Тестирование логирования
## Подключение
Для тестов следует подключать специальный модуль — **`LocalLoggerModule.forTesting()`**. Он
сохраняет логи в памяти и предоставляет к ним доступ через `TestingLogger`.
Это позволяет:
- перехватывать все вызовы логгера внутри тестируемого кода;
- сохранять их в память вместо вывода в консоль;
- проверять, какие именно логи были собраны за время теста.
Пример подключения через NestJS `TestingModule`:
```ts
let logger: TestingLogger;
beforeEach(async () => {
const module = await Test.createTestingModule({
imports: [LocalLoggerModule.forTesting()],
}).compile();
logger = module.get(TestingLogger);
});
```
После такого подключения любые вызовы вида:
```ts
this.logger.log('Brand created');
this.logger.error('Brand update failed');
```
будут сохранены внутри `TestingLogger`, и вы сможете проверить их в тестах при помощи матчеров:
```ts
logger.withMessage('Brand created').withLevel('info').toBeLoggedOnce();
logger.withMessage('Brand update failed').withLevel('error').toBeLogged();
```
## Цепочка фильтров
Методы фильтрации (`withMessage`, `withLevel`, `withContext`, `withDetails`) можно вызывать
цепочкой, для более точного сопоставления логов:
```ts
logger
.withMessage('Brand created')
.withLevel('info')
.withContext('Brands')
.withDetails({ user: 5 })
.toBeLoggedOnce();
```
Метод `withDetails` поддерживает частичное сравнение объекта, а также может проверять поля `level`,
`context` и `message`:
```ts
logger
.withMessage('Brand created')
.withDetails({
level: 'info',
context: 'Brands',
user: 5,
})
.toBeLoggedOnce();
```
Если нужны только поля из фильтра и ничего лишнего в `details`, к цепочке добавляется
`strictDetails()`.
### Просмотр найденных записей
Если нужно отладить фильтр и просмотреть, какие записи были найдены по текущему фильтру, можно
использовать метод `showLogs()`:
```ts
logger.withLevel('error').showLogs().toBeLogged();
```
### Методы проверки
| Метод | Описание |
| -------------------- | --------------------------------------------------------- |
| `toBeLogged()` | Проверяет, что хотя бы одна запись соответствует фильтру. |
| `toBeNotLogged()` | Проверяет, что таких записей нет. |
| `toBeLoggedOnce()` | Проверяет, что запись встречается ровно один раз. |
| `toBeLoggedTimes(n)` | Проверяет, что запись встречается `n` раз. |
Все методы выбрасывают ошибку, если условие не выполняется.
> **Важно:** Методы проверки **обязательно** должны вызываться, иначе проверки так и не будет.
### Группирование проверок
Если в тесте нужно проверить несколько событий с общим набором полей, можно использовать такой
приём:
```ts
const brandsLogger = logger.withContext('Brands');
brandsLogger.withMessage('Brand created').toBeLoggedTimes(2);
brandsLogger.withMessage('Brand update failed').toBeLoggedOnce();
```
Это удобно для группировки проверок по контексту или другим общим параметрам.
## Примеры использования
### Проверка бизнес-события
```ts
it('должен логировать создание бренда', () => {
service.createBrand({ user: 7 });
logger.withMessage('Brand created').withLevel('info').withDetails({ user: 7 }).toBeLoggedOnce();
});
```
### Проверка ошибок
```ts
it('должен логировать ошибку при невалидном статусе', () => {
service.updateBrandStatus(42, 'invalid');
logger.withMessage('Brand update failed').withLevel('error').toBeLogged();
});
```
### Проверка отсутствия логов
```ts
it('не должен логировать ничего при успешном выполнении без событий', () => {
service.doNothing();
logger.any().toBeNotLogged();
});
```
### Очистка
```ts
beforeEach(() => {
logger.clear();
});
```
Используйте `clear()` для сброса состояния между тестами, если экземпляр `TestingLogger`
переиспользуется в нескольких сценариях.
## Рекомендации
- `TestingLogger` предназначен **только для тестов** — в рабочем коде используется обычный `Logger`.
- Проверяйте **факт логирования**, а не реализацию — тесты должны оставаться устойчивыми к
внутренним изменениям.
- Используйте `toBeNotLogged()` для сценариев, где событие **не должно** быть зафиксировано.
- Готовый пример работы с `TestingLogger` — `apps/api/src/logger/testing/testing-logger.spec.ts`.
+1
View File
@@ -0,0 +1 @@
label: 'Логирование'