diff --git a/README.md b/README.md index 48f20b3..c5fae56 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ PostgreSQL, фронтенд на React + Vite, e2e-тесты, единый л | `apps/api-e2e` | e2e-тесты API на Jest | | `packages/` | общие библиотеки воркспейса | | `tools/` | скрипты воркспейса: сборка и проверка data source, снимок и восстановление БД | -| `docs/` | документация в MDX: слои приложений, БД, деплой | +| `docs/` | документация в MDX: слои приложений, БД, логирование, деплой | | `.gitea/workflows/` | CI/CD: `ci.yaml` (ветки), `production.yaml` (теги), `cleanup.yaml` | | `.gitea/issue_template/` | шаблоны задач Gitea | @@ -119,6 +119,7 @@ yarn nx affected -t # только по затронутым про - [Работа с БД](docs/50-developing/10-persistence.md), [миграции](docs/50-developing/20-migrations.md), [доступ к данным](docs/50-developing/30-data-access.md), [тесты](docs/50-developing/40-testing.md) +- [Ручное логирование](docs/55-logging/04-manual-logs.md) - [Миграции и деплой](docs/90-deploy/10-migrations.md) Инструкции для ИИ-агентов (в том числе Claude Code) — в [AGENTS.md](AGENTS.md). diff --git a/apps/api/Dockerfile b/apps/api/Dockerfile index b2598bb..05738e6 100644 --- a/apps/api/Dockerfile +++ b/apps/api/Dockerfile @@ -15,7 +15,10 @@ COPY --from=deps /app/node_modules /app/node_modules COPY ./dist /app EXPOSE 5000 +# Прод-режим по умолчанию: JSON-логи pino и никаких pino-pretty из devDependencies, +# которые в образ не попадают. Переопределяется через docker-compose при необходимости. ENV PORT=5000 +ENV NODE_ENV=production WORKDIR /app diff --git a/apps/api/package.json b/apps/api/package.json index 2d512dd..b70abdf 100644 --- a/apps/api/package.json +++ b/apps/api/package.json @@ -9,8 +9,12 @@ "@nestjs/swagger": "^11.4.7", "@nestjs/terminus": "^11.1.1", "axios": "^1.6.0", + "colorette": "^2.0.20", "dotenv": "^16.4.7", + "nestjs-pino": "^4.4.1", "pg": "^8.20.0", + "pino": "^9.11.0", + "pino-http": "^10.5.0", "reflect-metadata": "^0.1.13", "rxjs": "^7.8.0", "typeorm": "^0.3.31" @@ -18,6 +22,7 @@ "devDependencies": { "@nestjs/schematics": "^11.0.0", "@nestjs/testing": "^11.0.0", + "pino-pretty": "^13.1.1", "webpack-cli": "^5.1.4" } } diff --git a/apps/api/src/app/app.module.ts b/apps/api/src/app/app.module.ts index 22e614e..7a93bbf 100644 --- a/apps/api/src/app/app.module.ts +++ b/apps/api/src/app/app.module.ts @@ -1,11 +1,17 @@ -import { Module } from '@nestjs/common'; +import { Module, OnModuleDestroy } from '@nestjs/common'; + +import { LocalLoggerModule, Logger } from '../logger'; import { AppController } from './app.controller'; import { AppService } from './app.service'; @Module({ - imports: [], + imports: [LocalLoggerModule.forRoot()], controllers: [AppController], providers: [AppService], }) -export class AppModule {} +export class AppModule implements OnModuleDestroy { + onModuleDestroy() { + new Logger('AppModule').warn('Backend is shutting down'); + } +} diff --git a/apps/api/src/logger/base.ts b/apps/api/src/logger/base.ts new file mode 100644 index 0000000..c5e64a0 --- /dev/null +++ b/apps/api/src/logger/base.ts @@ -0,0 +1,36 @@ +import pino, { Logger as PinoLogger } from 'pino'; +import type { PrettyOptions } from 'pino-pretty'; + +/** + * В продакшене пишем машиночитаемый JSON, в остальных окружениях — человекочитаемый вывод. + * LOG_PRETTY явно перекрывает определение по NODE_ENV (нужно, когда образ собран под прод, + * а контейнер поднят локально). + */ +const isProduction = process.env.NODE_ENV === 'production' || process.env.LOG_PRETTY === 'false'; + +const baseLogger = pino({ + level: process.env.LOG_LEVEL ?? (isProduction ? 'info' : 'debug'), + transport: isProduction + ? undefined + : { + target: 'pino-pretty', + options: { + colorize: true, + translateTime: 'HH:MM:ss.l', + ignore: 'pid,hostname,context,reqId,res,url,statusCode,responseTime', + messageFormat: [ + '\x1b[36m{reqId}\x1b[0m', + '\x1b[33m{context}\x1b[0m', + '\x1b[34m{msg}\x1b[0m', + ].join(' '), + } as PrettyOptions, + }, +}); + +/** + * Единственный экземпляр pino на процесс: и корневой логгер приложения, и pino-http + * пишут через него, поэтому транспорт (воркер pino-pretty) создаётся один раз. + */ +export function getBaseLogger(): PinoLogger { + return baseLogger; +} diff --git a/apps/api/src/logger/index.ts b/apps/api/src/logger/index.ts new file mode 100644 index 0000000..d40260a --- /dev/null +++ b/apps/api/src/logger/index.ts @@ -0,0 +1,3 @@ +export * from './base'; +export * from './logger.class'; +export * from './logger.module'; diff --git a/apps/api/src/logger/logger.class.ts b/apps/api/src/logger/logger.class.ts new file mode 100644 index 0000000..f10f32e --- /dev/null +++ b/apps/api/src/logger/logger.class.ts @@ -0,0 +1,167 @@ +import { Inject, Injectable, LoggerService, Scope } from '@nestjs/common'; +import { PinoLogger } from 'nestjs-pino'; +import { Bindings } from 'pino'; + +import { getBaseLogger } from './base'; + +export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'; + +@Injectable({ scope: Scope.TRANSIENT }) +export class Logger implements LoggerService { + private readonly logger: PinoLogger; + + constructor(); + constructor(context: string); + constructor( + @Inject(PinoLogger) + context?: string | PinoLogger, + ) { + if (context && context instanceof PinoLogger) { + this.logger = context; + } else { + const bindings: Bindings = context ? { context } : {}; + + this.logger = getBaseLogger().child(bindings) as unknown as PinoLogger; + } + } + + setContext(context: string) { + if (this.logger instanceof PinoLogger) { + this.logger.setContext(context); + } else { + throw new Error('Cannot set context on child logger'); + } + } + + /** + * Трассировка, максимальная детализация + * + * Log level: 10 + * + * Самый подробный уровень. Используется для сложных расследований и поиска причин ошибок. + * + * Примеры: + * - пошаговое логирование алгоритма + * - шаги в обработке запроса + * - переходы между этапами обработки + * - детали бизнес-логики + */ + trace(message: string, details?: object) { + this.logInner('trace', message, details); + } + + /** + * Отладка, подробности бизнес-логики + * + * Log level: 20 + * + * Сообщения для разработчиков, полезные при разборе логики работы. + * + * Примеры: + * - запрос разрешений + * - ключевые шаги алгоритма + * - получение данных из внешних сервисов + * - события жизненного цикла приложения + * - ответы от внешних сервисов + */ + debug(message: string, details?: object) { + this.logInner('debug', message, details); + } + + /** + * Ключевые события приложения + * + * Log level: 30 + * + * Информационные сообщения о нормальной работе приложения. + * + * Примеры: + * - запрос к API + * - пользователь успешно вошёл в систему + * - заявка создана + * - бизнес-операция успешно выполнена + */ + log(message: string, details?: object) { + this.logInner('info', message, details); + } + + /** + * Потенциальная проблема, нестандартное поведение + * + * Log level: 40 + * + * Предупреждения о нежелательных или подозрительных ситуациях, которые не приводят к немедленной поломке. + * + * Примеры: + * - потенциально опасное поведение пользователя + * - использование устаревшего API + * - медленный запрос + */ + warn(message: string, details?: object) { + this.logInner('warn', message, details); + } + + /** + * Ошибка, требующая реакции + * + * Log level: 50 + * + * Серьёзные ошибки в работе приложения, которые нужно обрабатывать. + * + * Примеры: + * - API отдало 500 + * - не удалось выполнить бизнес-операцию. + */ + error(message: string, details?: object): void; + /** + * Ошибка, требующая реакции + * + * Log level: 50 + * + * Серьёзные ошибки в работе приложения, которые нужно обрабатывать. + * + * Примеры: + * - API отдало 500 + * - не удалось выполнить бизнес-операцию. + */ + error(message: string, trace?: string, details?: object): void; + error(message: string, traceOrDetails?: string | object, details?: object | string) { + if (typeof details === 'string') { + details = { context: details }; + } + + if (typeof traceOrDetails === 'string') { + details = { ...details, trace: traceOrDetails }; + } + + this.logInner('error', message, details); + } + + /** + * Критическая ошибка, завершение работы + * + * Log level: 60 + * + * Используется для ситуаций, после которых приложение не может продолжать работу. + * + * Примеры: + * - падение основного процесса + * - невозможность поднять сервер на указанном порту + * - не корректная конфигурация + * - не удалось подключиться к базе данных + */ + fatal(message: string, details?: object) { + this.logInner('fatal', message, details); + } + + protected logInner(level: LogLevel, message: string, details?: object | string) { + if (typeof details === 'object' && details !== null) { + this.logger[level](details, message); + } else if (typeof details === 'string') { + // Для совместимости с логгером по умолчанию в NestJS + this.logger[level]({ context: details }, message); + } else { + this.logger[level](message); + } + } +} diff --git a/apps/api/src/logger/logger.module.ts b/apps/api/src/logger/logger.module.ts new file mode 100644 index 0000000..e0662a5 --- /dev/null +++ b/apps/api/src/logger/logger.module.ts @@ -0,0 +1,113 @@ +import { IncomingMessage, ServerResponse } from 'http'; + +import { DynamicModule, INestApplication, Module } from '@nestjs/common'; +import { LoggerModule, PinoLogger } from 'nestjs-pino'; + +import { getBaseLogger } from './base'; +import { Logger } from './logger.class'; +import { MockLogger, TestingLogger } from './testing'; + +@Module({}) +export class LocalLoggerModule { + /** + * Рабочая конфигурация: наш pino (base.ts) + автоматические HTTP-логи через pino-http. + */ + public static forRoot(): DynamicModule { + return { + global: true, + module: LocalLoggerModule, + imports: [ + LoggerModule.forRoot({ + pinoHttp: { + // важное место: используем наш СУЩЕСТВУЮЩИЙ pino, а не создаём новый + logger: getBaseLogger(), + + autoLogging: true, + + customProps: (req: IncomingMessage) => ({ + url: req.method + ' ' + req.url, + context: 'HTTP', + }), + quietReqLogger: true, + quietResLogger: true, + + customLogLevel: function ( + _req: IncomingMessage, + res: ServerResponse, + err?: Error, + ) { + if (res.statusCode >= 500 || err) { + return 'error'; + } else if (res.statusCode >= 300 && res.statusCode < 400) { + return 'silent'; + } + + return 'info'; + }, + customSuccessMessage(req: IncomingMessage, res: ServerResponse) { + return `Request completed: ${res.statusCode} ${req.method} ${req.url}`; + }, + customSuccessObject( + _req: IncomingMessage, + res: ServerResponse, + val: { responseTime: number }, + ) { + return { + statusCode: res.statusCode, + responseTime: val.responseTime, + }; + }, + customErrorMessage(req: IncomingMessage, res: ServerResponse, err: Error) { + return `Request error: ${res.statusCode} ${req.method} ${req.url} ${err.message}`; + }, + customErrorObject( + req: IncomingMessage, + res: ServerResponse, + _err: Error, + val: { responseTime: number }, + ) { + return { + url: req.method + ' ' + req.url, + statusCode: res.statusCode, + responseTime: val.responseTime, + }; + }, + }, + }), + ], + providers: [Logger], + exports: [Logger], + }; + } + + /** + * Конфигурация для тестов: логи складываются в память и проверяются через TestingLogger. + */ + public static forTesting(): DynamicModule { + return { + global: true, + module: LocalLoggerModule, + providers: [ + TestingLogger, + { + provide: Logger, + useFactory: (testingLogger: TestingLogger) => new MockLogger(testingLogger), + inject: [TestingLogger], + }, + { + provide: PinoLogger, + useValue: {}, + }, + ], + exports: [Logger, TestingLogger], + }; + } + + /** + * Подмена логгера Nest нашим. Вызывать после NestFactory.create с bufferLogs: true — + * useLogger сбрасывает буфер в наш логгер. + */ + public static setup(app: INestApplication) { + app.useLogger(new Logger()); + } +} diff --git a/apps/api/src/logger/testing/index.ts b/apps/api/src/logger/testing/index.ts new file mode 100644 index 0000000..9acc7e7 --- /dev/null +++ b/apps/api/src/logger/testing/index.ts @@ -0,0 +1,2 @@ +export * from './logger.class'; +export * from './testing-logger.class'; diff --git a/apps/api/src/logger/testing/logger.class.ts b/apps/api/src/logger/testing/logger.class.ts new file mode 100644 index 0000000..b40ff8f --- /dev/null +++ b/apps/api/src/logger/testing/logger.class.ts @@ -0,0 +1,19 @@ +import { Logger, LogLevel } from '../logger.class'; + +import { TestingLogger } from './testing-logger.class'; + +export class MockLogger extends Logger { + private context: string; + + constructor(private readonly testingLogger: TestingLogger) { + super(); + } + + override setContext(context: string) { + this.context = context; + } + + protected override logInner(level: LogLevel, message: string, details?: object) { + this.testingLogger.log(level, message, this.context, details); + } +} diff --git a/apps/api/src/logger/testing/testing-logger.class.ts b/apps/api/src/logger/testing/testing-logger.class.ts new file mode 100644 index 0000000..630d880 --- /dev/null +++ b/apps/api/src/logger/testing/testing-logger.class.ts @@ -0,0 +1,265 @@ +import * as colorette from 'colorette'; + +import { LogLevel } from '../logger.class'; + +import { fail, LogEntry, PrettifyStackTrace, showLogDetails, showLogObject } from './utils'; + +export type { LogEntry }; + +export class TestingLogger { + private readonly entries: LogEntry[] = []; + + /** + * Добавление записи лога + */ + log(level: LogLevel, message: string, context: string, details?: object) { + this.entries.push({ + level, + message, + context, + ...details, + }); + } + + /** + * Очистка всех записей логов + */ + clear() { + this.entries.length = 0; + } + + /** + * Любые логи (старт без фильтра) + */ + any(): TestingLoggerMatcher { + return new TestingLoggerMatcher(this.entries, {}); + } + + /** + * Старт от фильтра по сообщению + */ + withMessage(message: string): TestingLoggerMatcher { + return new TestingLoggerMatcher(this.entries, { message }); + } + + /** + * Старт от фильтра по уровню + */ + withLevel(level: LogLevel): TestingLoggerMatcher { + return new TestingLoggerMatcher(this.entries, { level }); + } + + /** + * Старт от фильтра по контексту + */ + withContext(context: string): TestingLoggerMatcher { + return new TestingLoggerMatcher(this.entries, { context }); + } +} + +const BASE_FIELDS: (keyof LogEntry)[] = ['level', 'message', 'context']; + +export class TestingLoggerMatcher { + constructor( + private readonly entries: LogEntry[], + private readonly filter: Partial, + private readonly strict = false, + ) {} + + get logs() { + // В режиме strict мы хотим строгое совпадение деталей: все ключи деталей должны совпадать + // и не должно быть лишних ключей деталей у записи. + if (this.strict) { + return this.entries.filter((log) => { + // проверяем базовые поля, если они заданы в фильтре + for (const field of BASE_FIELDS) { + if (this.filter[field] !== undefined && log[field] !== this.filter[field]) { + return false; + } + } + + // ключи деталей в фильтре и в самой записи + const detailFilterKeys = Object.keys(this.filter).filter((k) => { + return !BASE_FIELDS.includes(k as keyof LogEntry); + }); + const entryDetailKeys = Object.keys(log).filter((k) => { + return !BASE_FIELDS.includes(k as keyof LogEntry); + }); + + // размеры наборов деталей должны совпадать + if (detailFilterKeys.length !== entryDetailKeys.length) { + return false; + } + + // все ключи из фильтра должны присутствовать и иметь одинаковые значения + return detailFilterKeys.every((key) => { + return log[key] === this.filter[key]; + }); + }); + } + + return this.entries.filter((log) => { + for (const key in this.filter) { + if (log[key] !== this.filter[key]) { + return false; + } + } + + return true; + }); + } + + showLogs(options: { hideFilter?: boolean; logs?: LogEntry[] } = {}): this { + const { hideFilter = false, logs = this.logs } = options; + + process.stdout.write(colorette.bold(colorette.white('--- Logs ---')) + '\n'); + + if (!hideFilter) { + process.stdout.write(colorette.bold(colorette.cyan('Filter:')) + '\n'); + + if (Object.keys(this.filter).length === 0) { + process.stdout.write(' (no filter, showing all logs)\n'); + } else { + showLogDetails({ + level: this.filter.level, + context: this.filter.context, + message: this.filter.message, + ...this.filter, + }); + } + } + + process.stdout.write(colorette.bold(colorette.white('Found logs:')) + '\n'); + + logs.forEach((log) => { + showLogObject(log); + process.stdout.write('\n'); // пустая строка между логами + }); + + process.stdout.write(` Found ${logs.length} log(s) total\n\n`); + + return this; + } + + /** + * Фильтр по сообщению + */ + withMessage(message: string): TestingLoggerMatcher { + return new TestingLoggerMatcher(this.entries, { ...this.filter, message }, this.strict); + } + + /** + * Фильтр по уровню + */ + withLevel(level: LogLevel): TestingLoggerMatcher { + return new TestingLoggerMatcher(this.entries, { ...this.filter, level }, this.strict); + } + + /** + * Фильтр по контексту + */ + withContext(context: string): TestingLoggerMatcher { + return new TestingLoggerMatcher(this.entries, { ...this.filter, context }, this.strict); + } + + /** + * Фильтр по дополнительным деталям + */ + withDetails(obj: Record): TestingLoggerMatcher { + return new TestingLoggerMatcher(this.entries, { ...this.filter, ...obj }, this.strict); + } + + /** + * Фильтр по дополнительным деталям - строгий (все детали должны совпадать, лишних быть не должно) + */ + strictDetails(): TestingLoggerMatcher { + return new TestingLoggerMatcher(this.entries, { ...this.filter }, true); + } + + /** + * Проверка наличия логов + */ + @PrettifyStackTrace() + toBeLogged(): void { + if (this.logs.length === 0) { + if (this.entries.length) { + this.toBeLoggedTimes(1); + } else { + return fail('No logs recorded'); + } + } + } + + /** + * Проверка отсутствия логов + */ + @PrettifyStackTrace() + toBeNotLogged(): void { + this.toBeLoggedTimes(0); + } + + /** + * Проверка, что лог был записан ровно один раз + */ + @PrettifyStackTrace() + toBeLoggedOnce(): void { + this.toBeLoggedTimes(1); + } + + /** + * Проверка, что лог был записан ровно n раз + */ + @PrettifyStackTrace() + toBeLoggedTimes(n: number): void { + if (this.logs.length === n) { + return; + } + + this.throwDiff(n); + } + + private throwDiff(n: number) { + if (!this.entries.length) { + return fail('No logs recorded'); + } + + throw new Error( + [ + `Expected ${n} log(s)` + describedFilter(this.filter), + this.logs.length ? '\nFound:' : '', + ...this.logs.map((entry) => ` ${logEntryToString(this.filter)(entry)}`), + this.logs.length ? '' : ' (none)', + ].join('\n'), + ); + } +} + +function describedFilter(filter: Partial): string { + const keys = Object.keys(filter); + + if (!keys.length) { + return ''; + } + + return ` matching ${keys.map((key) => `${key}=${String(filter[key])}`).join(', ')}`; +} + +function logEntryToString(filter: Partial) { + return (entry: LogEntry): string => { + let result = ''; + + if (filter.context) { + result += `${entry.context} `; + } + + if (filter.level) { + result += `[${entry.level}] `; + } + + if (filter.message) { + result += `${entry.message}`; + } + + return result; + }; +} diff --git a/apps/api/src/logger/testing/testing-logger.spec.ts b/apps/api/src/logger/testing/testing-logger.spec.ts new file mode 100644 index 0000000..829c6eb --- /dev/null +++ b/apps/api/src/logger/testing/testing-logger.spec.ts @@ -0,0 +1,567 @@ +import { Test } from '@nestjs/testing'; +import { beforeEach, describe, expect, it } from 'vitest'; + +import { Logger } from '../logger.class'; +import { LocalLoggerModule } from '../logger.module'; + +import { TestingLogger } from './testing-logger.class'; + +describe('TestingLogger', () => { + let mockLogger: Logger; + let logger: TestingLogger; + + beforeEach(async () => { + const module = await Test.createTestingModule({ + imports: [LocalLoggerModule.forTesting()], + }).compile(); + + mockLogger = await module.resolve(Logger); + logger = module.get(TestingLogger); + }); + + it('complex test', () => { + // Arrange + mockLogger.setContext('RBAC'); + + // Act + mockLogger.debug('Access granted', { user: 1, permissions: ['read'] }); + mockLogger.log('Access granted', { user: 2, permissions: ['read', 'write'] }); + mockLogger.warn('Access denied', { user: 1 }); + mockLogger.log('User logged in', { user: 1 }); + mockLogger.error('Unexpected error', { error: new Error('Test error') }); + + // Assert + const rbacLogger = logger.withContext('RBAC'); + + rbacLogger.withMessage('Access denied').toBeLogged(); + + rbacLogger.withMessage('Access granted').withLevel('debug').toBeLogged(); + rbacLogger.withMessage('Access granted').withLevel('info').toBeLogged(); + rbacLogger.withMessage('User logged in').withLevel('info').toBeLogged(); + rbacLogger.withMessage('Unexpected error').withLevel('error').toBeLogged(); + + rbacLogger.toBeLoggedTimes(5); + + rbacLogger.withMessage('Access granted').toBeLoggedTimes(2); + rbacLogger.withMessage('Access denied').toBeLoggedOnce(); + rbacLogger.withMessage('User logged in').toBeLoggedOnce(); + rbacLogger.withMessage('Unexpected error').toBeLoggedOnce(); + + rbacLogger.withMessage('Access granted').withDetails({ user: 1 }).toBeLoggedOnce(); + }); + + describe('TestingLogger — базовые операции', () => { + it('сохраняет запись через log() (все поля + details)', () => { + // Arrange + logger.log('info', 'msg', 'CTX', { a: 1 }); + + // Act + const matcher = logger.any(); + + // Assert + matcher.toBeLoggedOnce(); + // Проверяем точное соответствие + const entries = matcher.logs; + + expect(entries[0]).toEqual({ + level: 'info', + message: 'msg', + context: 'CTX', + a: 1, + }); + }); + + it('log() без details не добавляет лишних ключей', () => { + // Arrange + logger.log('warn', 'msg', 'CTX'); + + // Act + const matcher = logger.any(); + + matcher.toBeLoggedOnce(); + const entry = matcher.logs[0]; + + // Assert + expect(entry).toEqual({ + level: 'warn', + message: 'msg', + context: 'CTX', + }); + // Проверяем отсутствие произвольных ключей + expect(entry.a).toBeUndefined(); + expect(entry.b).toBeUndefined(); + }); + + it('поля из details перекрывают базовые при совпадении ключей', () => { + // Arrange + logger.log('info', 'base', 'CTX', { + message: 'override', + level: 'error', + context: 'OVR', + }); + + // Act + const matcher = logger.any(); + + matcher.toBeLoggedOnce(); + const entry = matcher.logs[0]; + + // Assert + expect(entry).toEqual({ + level: 'error', + message: 'override', + context: 'OVR', + }); + }); + + it('clear() очищает все записи', () => { + // Arrange + logger.log('info', 'A', 'CTX'); + logger.log('warn', 'B', 'CTX'); + + // Act + logger.clear(); + const matcher = logger.any(); + + // Assert + matcher.toBeNotLogged(); + }); + }); + + describe('TestingLogger — входные точки фильтрации', () => { + it('any() возвращает матчёр со всеми текущими записями', () => { + // Arrange + logger.log('info', 'A', 'CTX1'); + logger.log('warn', 'B', 'CTX2'); + logger.log('error', 'C', 'CTX3'); + + // Act & Assert + logger.any().toBeLoggedTimes(3); + }); + + it('withMessage("X") создаёт стартовый матчёр с фильтром по message', () => { + // Arrange + logger.log('info', 'X', 'CTX1'); + logger.log('warn', 'Y', 'CTX2'); + logger.log('error', 'X', 'CTX3'); + + // Act & Assert + logger.withMessage('X').toBeLoggedTimes(2); + logger.withMessage('Y').toBeLoggedTimes(1); + logger.withMessage('Z').toBeLoggedTimes(0); + }); + + it('withLevel(L) создаёт стартовый матчёр с фильтром по level', () => { + // Arrange + logger.log('info', 'A', 'CTX1'); + logger.log('error', 'B', 'CTX2'); + logger.log('error', 'C', 'CTX3'); + + // Act & Assert + logger.withLevel('info').toBeLoggedTimes(1); + logger.withLevel('error').toBeLoggedTimes(2); + logger.withLevel('warn').toBeLoggedTimes(0); + }); + + it('withContext("C") создаёт стартовый матчёр с фильтром по context', () => { + // Arrange + logger.log('info', 'A', 'C'); + logger.log('warn', 'B', 'CTX2'); + logger.log('error', 'C', 'C'); + + // Act & Assert + logger.withContext('C').toBeLoggedTimes(2); + logger.withContext('CTX2').toBeLoggedTimes(1); + logger.withContext('CTX3').toBeLoggedTimes(0); + }); + + it('повторные вызовы стартовых фильтров независимы (каждый — новый матчёр)', () => { + // Arrange + logger.log('info', 'A', 'CTX'); + logger.log('info', 'B', 'CTX'); + + // Act + const mA = logger.withMessage('A'); + const mB = logger.withMessage('B'); + + // Assert + mA.toBeLoggedTimes(1); + mB.toBeLoggedTimes(1); + // Проверяем, что фильтры независимы + expect(mA.logs[0].message).toBe('A'); + expect(mB.logs[0].message).toBe('B'); + }); + }); + + describe('TestingLoggerMatcher — фильтры (локальные)', () => { + it('withMessage("X") фильтрует текущий набор по message', () => { + // Arrange + logger.log('info', 'X', 'CTX1'); + logger.log('warn', 'Y', 'CTX2'); + logger.log('error', 'X', 'CTX3'); + logger.log('debug', 'Z', 'CTX4'); + + // Act + const filtered = logger.any().withMessage('X'); + + // Assert + filtered.toBeLoggedTimes(2); // Должно остаться только 2 записи с message === 'X' + }); + + it('withLevel(L) фильтрует текущий набор по level', () => { + // Arrange + logger.log('warn', 'A', 'CTX1'); + logger.log('info', 'B', 'CTX2'); + logger.log('warn', 'C', 'CTX3'); + logger.log('error', 'D', 'CTX4'); + + // Act + const filtered = logger.any().withLevel('warn'); + + // Assert + filtered.toBeLoggedTimes(2); // Должно остаться только 2 записи с level === 'warn' + }); + + it('withContext("C") фильтрует текущий набор по context', () => { + // Arrange + logger.log('warn', 'A', 'C'); + logger.log('info', 'B', 'CTX2'); + logger.log('warn', 'C', 'C'); + logger.log('error', 'D', 'CTX4'); + + // Act + const filtered = logger.any().withContext('C'); + + // Assert + filtered.toBeLoggedTimes(2); // Должно остаться только 2 записи с context === 'C' + }); + + it('withDetails({k:v}) оставляет записи, где все пары совпали (логическое И)', () => { + // Arrange + logger.log('info', 'A', 'CTX', { a: 1, b: 'x' }); + logger.log('info', 'B', 'CTX', { a: 1 }); + logger.log('info', 'C', 'CTX', { b: 'x' }); + logger.log('info', 'D', 'CTX', { a: 1, b: 'x', c: true }); + + // Act + const filtered = logger.any().withDetails({ a: 1, b: 'x' }); + + // Assert + filtered.toBeLoggedTimes(2); // Должны остаться только записи, где одновременно a=1 и b='x' + }); + + it('комбинация фильтров даёт пересечение условий', () => { + // Arrange + logger.log('info', 'X', 'C', { a: 1 }); // подходит + logger.log('info', 'X', 'C', { a: 2 }); // не подходит + logger.log('info', 'Y', 'C', { a: 1 }); // не подходит + logger.log('warn', 'X', 'C', { a: 1 }); // не подходит + + // Act + const filtered = logger + .any() + .withMessage('X') + .withLevel('info') + .withContext('C') + .withDetails({ a: 1 }); + + // Assert + filtered.toBeLoggedTimes(1); // Только одна запись удовлетворяет всем условиям + }); + + it('порядок применения with* не влияет на результат (коммутативность)', () => { + // Arrange + logger.log('info', 'X', 'C', { a: 1 }); // подходит + logger.log('info', 'X', 'C', { a: 2 }); // не подходит + logger.log('info', 'Y', 'C', { a: 1 }); // не подходит + logger.log('warn', 'X', 'C', { a: 1 }); // не подходит + + // Act + const filtered1 = logger + .any() + .withMessage('X') + .withLevel('info') + .withContext('C') + .withDetails({ a: 1 }); + const filtered2 = logger + .any() + .withDetails({ a: 1 }) + .withContext('C') + .withLevel('info') + .withMessage('X'); + + // Assert + filtered1.toBeLoggedTimes(1); + filtered2.toBeLoggedTimes(1); + }); + + it('фильтры не мутируют исходный матчёр (иммутабельность)', () => { + // Arrange + logger.log('info', 'X', 'CTX'); + logger.log('info', 'Y', 'CTX'); + + // Act + const m0 = logger.any(); + const m1 = m0.withMessage('X'); + + // Assert + m0.toBeLoggedTimes(2); // исходный набор + m1.toBeLoggedTimes(1); // отфильтрованный + m0.toBeLoggedTimes(2); // повторно исходный набор + }); + + it('фильтр на пустом наборе остаётся пустым', () => { + // Arrange + logger.log('info', 'A', 'CTX'); + + // Act & Assert + logger + .any() + .withMessage('non-existent') + .withLevel('warn') + .withContext('none') + .toBeLoggedTimes(0); + }); + + it('через withDetails можно проверять и другие поля', () => { + // Arrange + logger.log('info', 'A', 'CTX'); + + // Act & Assert + logger + .any() + .withMessage('A') + .withDetails({ level: 'info', context: 'CTX' }) + .toBeLoggedOnce(); + }); + }); + + describe('Паритет фильтров в обоих классах', () => { + it('старт с TestingLogger.withX(...).withY(...).withZ(...) == any().withX(...).withY(...).withZ(...)', () => { + // Arrange + logger.log('info', 'X', 'C', { a: 1 }); // подходит + logger.log('info', 'X', 'C', { a: 2 }); // не подходит + logger.log('info', 'Y', 'C', { a: 1 }); // не подходит + logger.log('warn', 'X', 'C', { a: 1 }); // не подходит + + // Act + const fromStart = logger + .withMessage('X') + .withLevel('info') + .withContext('C') + .withDetails({ a: 1 }); + const fromAny = logger + .any() + .withMessage('X') + .withLevel('info') + .withContext('C') + .withDetails({ a: 1 }); + + // Assert + fromStart.toBeLoggedTimes(1); + fromAny.toBeLoggedTimes(1); + // Проверяем, что состав совпадает + expect(JSON.stringify(fromStart.logs)).toBe(JSON.stringify(fromAny.logs)); + }); + }); + + describe('Матчеры наличия/отсутствия', () => { + it('toBeLogged() проходит при >= 1 записи', () => { + // Arrange + logger.log('info', 'A', 'CTX'); + + // Act & Assert + expect(() => logger.any().toBeLogged()).not.toThrow(); + }); + + it('toBeLogged() падает на пустом наборе', () => { + // Arrange: ничего не добавляем + + // Act & Assert + expect(() => logger.any().toBeLogged()).toThrowError('No logs recorded'); + }); + + it('toBeNotLogged() проходит при 0 записях', () => { + // Arrange: ничего не добавляем + + // Act & Assert + expect(() => logger.any().toBeNotLogged()).not.toThrow(); + }); + + it('toBeNotLogged() падает при >= 1 записи', () => { + // Arrange + logger.log('info', 'A', 'CTX'); + logger.log('warn', 'B', 'CTX'); + + // Act & Assert + expect(() => logger.any().toBeNotLogged()).toThrow(); + }); + }); + + describe('Матчеры количества', () => { + it('toBeLoggedOnce() проходит при ровно 1 записи', () => { + // Arrange + logger.log('info', 'A', 'CTX'); + + // Act & Assert + expect(() => logger.any().toBeLoggedOnce()).not.toThrow(); + }); + + it('toBeLoggedOnce() падает при 0', () => { + // Сценарий A: 0 записей + expect(() => logger.any().toBeLoggedOnce()).toThrow(); + }); + + it('toBeLoggedOnce() падает при >1, сообщение содержит count и JSON', () => { + // Сценарий B: >1 записей + logger.log('info', 'A', 'CTX'); + logger.log('info', 'B', 'CTX'); + + expect(() => logger.any().toBeLoggedOnce()).toThrow(); + }); + + it('toBeLoggedTimes(n) проходит при точном совпадении количества', () => { + // Arrange + logger.log('info', 'A', 'CTX'); + logger.log('info', 'B', 'CTX'); + + // Act & Assert + expect(() => logger.any().toBeLoggedTimes(2)).not.toThrow(); + }); + + it('toBeLoggedTimes(n) падает при несовпадении (сообщение: ожидаемое и фактическое)', () => { + // Arrange + logger.log('info', 'A', 'CTX'); + + // Act & Assert + expect(() => logger.any().toBeLoggedTimes(2)).toThrow(); + }); + + it('toBeLoggedTimes(0) проходит на пустом наборе', () => { + // Arrange: ничего не добавляем + + // Act & Assert + expect(() => logger.any().toBeLoggedTimes(0)).not.toThrow(); + }); + }); + + describe('Детали и типы значений (withDetails / details)', () => { + it('совпадение по string/number/boolean', () => { + // Arrange + logger.log('info', 'A', 'CTX', { a: 'x' }); + logger.log('info', 'B', 'CTX', { b: 1 }); + logger.log('info', 'C', 'CTX', { c: true }); + + // Act & Assert + logger.any().withDetails({ a: 'x' }).toBeLoggedOnce(); + logger.any().withDetails({ b: 1 }).toBeLoggedOnce(); + logger.any().withDetails({ c: true }).toBeLoggedOnce(); + }); + + it('несуществующий ключ в фильтре исключает запись', () => { + // Arrange + logger.log('info', 'A', 'CTX', { a: 1 }); + + // Act & Assert + logger.any().withDetails({ d: 42 }).toBeLoggedTimes(0); + }); + + it('частичное несоответствие по одному из ключей исключает запись', () => { + // Arrange + logger.log('info', 'A', 'CTX', { a: 1, b: 2 }); + + // Act & Assert + logger.any().withDetails({ a: 1, b: 999 }).toBeLoggedTimes(0); + }); + + it('различие по типу (число vs строка) не считается совпадением', () => { + // Arrange + logger.log('info', 'A', 'CTX', { a: 1 }); + + // Act & Assert + logger + .any() + .withDetails({ a: '1' as unknown as number }) + .toBeLoggedTimes(0); + }); + + it('дополнительные поля в записи не мешают совпадению (подмножество)', () => { + // Arrange + logger.log('info', 'A', 'CTX', { a: 1, b: 2, c: 3 }); + + // Act & Assert + logger.any().withDetails({ a: 1 }).toBeLoggedOnce(); + }); + + it('strictDetails требует точного совпадения ключей деталей (не допускает лишних полей)', () => { + // Arrange + logger.log('info', 'X', 'CTX', { a: 1, b: 2 }); + + // Act & Assert + // Обычный withDetails допускает совпадение по подмножеству + logger.any().withDetails({ a: 1 }).toBeLoggedOnce(); + + // strictDetails требует точного совпадения — запись с лишним полем не должна подходить + logger.any().withDetails({ a: 1 }).strictDetails().toBeLoggedTimes(0); + }); + + it('strictDetails проходит при полном совпадении деталей', () => { + // Arrange + logger.log('info', 'Y', 'CTX', { a: 1 }); + + // Act & Assert + logger.any().withDetails({ a: 1 }).strictDetails().toBeLoggedOnce(); + }); + }); + + describe('Граничные случаи', () => { + it('дубликаты идентичных логов учитываются поштучно в подсчёте', () => { + // Arrange + logger.log('info', 'A', 'CTX', { a: 1 }); + logger.log('info', 'A', 'CTX', { a: 1 }); + logger.log('info', 'A', 'CTX', { a: 1 }); + + // Act & Assert + logger.any().withDetails({ a: 1 }).toBeLoggedTimes(3); + }); + + it('одинаковые level/message/context, но разные details различаются withDetails', () => { + // Arrange + logger.log('info', 'A', 'CTX', { a: 1 }); + logger.log('info', 'A', 'CTX', { a: 2 }); + + // Act & Assert + logger.any().withDetails({ a: 1 }).toBeLoggedOnce(); + logger.any().withDetails({ a: 2 }).toBeLoggedOnce(); + }); + + it('пустые строки корректно фильтруются: withMessage("") / withContext("")', () => { + // Arrange + logger.log('info', '', 'CTX', { a: 1 }); + logger.log('info', 'A', '', { a: 2 }); + logger.log('info', '', '', { a: 3 }); + + // Act & Assert + logger.withMessage('').toBeLoggedTimes(2); // две записи с пустым message + logger.withContext('').toBeLoggedTimes(2); // две записи с пустым context + }); + + it('smoke: большое количество записей не ломает фильтры', () => { + // Arrange + const N = 1000; + + for (let i = 0; i < N; i++) { + logger.log('info', `msg${i % 10}`, `CTX${i % 5}`, { a: i % 3, b: i }); + } + + // Act & Assert + logger.withMessage('msg1').toBeLoggedTimes(100); + logger.withContext('CTX2').toBeLoggedTimes(200); + logger + .any() + .withDetails({ a: 0 }) + .toBeLoggedTimes(Math.floor(N / 3) + (N % 3 > 0 ? 1 : 0)); + logger.any().withDetails({ b: 42 }).toBeLoggedOnce(); + }); + }); +}); diff --git a/apps/api/src/logger/testing/utils.ts b/apps/api/src/logger/testing/utils.ts new file mode 100644 index 0000000..90677a6 --- /dev/null +++ b/apps/api/src/logger/testing/utils.ts @@ -0,0 +1,65 @@ +import * as colorette from 'colorette'; + +import { LogLevel } from '../logger.class'; + +export interface LogEntry { + level: LogLevel; + message: string; + context: string; + [extra: string]: unknown; +} + +export function fail(message: string): void { + throw new Error(message); +} + +type ErrorConstructorWithCapture = ErrorConstructor & { + captureStackTrace?: (targetObject: object, constructorOpt?: unknown) => void; +}; + +/** + * Декоратор для методов матчеров: + * Если метод бросил ошибку — стек "подрезается" так, + * чтобы указать на строку вызова матчера в тесте (а не внутрь реализации). + */ +export function PrettifyStackTrace(): MethodDecorator { + return (_target, _key, descriptor: PropertyDescriptor) => { + const original = descriptor.value as (...args: unknown[]) => unknown; + + function wrap(this: unknown, ...args: unknown[]) { + try { + return original.apply(this, args); + } catch (err) { + (Error as ErrorConstructorWithCapture).captureStackTrace?.(err as object, wrap); + + throw err; + } + } + + descriptor.value = wrap; + + return descriptor; + }; +} + +export function showLogObject({ level, context, message, ...details }: LogEntry) { + const l = colorette.blue(level); + const c = colorette.bold(colorette.magenta(context)); + const m = colorette.underline(colorette.white(message)); + + process.stdout.write(` ${l} ${c} ${m}\n`); + + showLogDetails(details); +} + +export function showLogDetails(details: Record) { + Object.keys(details).forEach((key) => { + if (details[key] === undefined) { + return; + } + + process.stdout.write( + ` ${colorette.blue(key)}: ${colorette.yellow(String(details[key]))}\n`, + ); + }); +} diff --git a/apps/api/src/main.ts b/apps/api/src/main.ts index ab2a7f1..69b7349 100644 --- a/apps/api/src/main.ts +++ b/apps/api/src/main.ts @@ -2,11 +2,24 @@ import { NestFactory } from '@nestjs/core'; import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'; import { AppModule } from './app/app.module'; +import { getBaseLogger, LocalLoggerModule, Logger } from './logger'; async function start() { const PORT = process.env.PORT || 5000; - const app = await NestFactory.create(AppModule); + const app = await NestFactory.create(AppModule, { + bufferLogs: true, + }); + + // Подменяем логгер Nest на pino; накопленный в буфере вывод сбрасывается в него же + LocalLoggerModule.setup(app); + + const logger = new Logger('Bootstrap'); + + logger.log('Logging started', { + level: getBaseLogger().level, + pretty: process.env.NODE_ENV !== 'production' && process.env.LOG_PRETTY !== 'false', + }); // настройка swaggera const config = new DocumentBuilder() @@ -41,6 +54,9 @@ async function start() { allowedHeaders: 'Content-Type, Authorization', credentials: true, }); - await app.listen(PORT, () => console.log(`Server started on ${PORT}`)); + + await app.listen(PORT); + + logger.log('Server started', { port: PORT }); } start(); diff --git a/docs/55-logging/01-overview.md b/docs/55-logging/01-overview.md new file mode 100644 index 0000000..5c24315 --- /dev/null +++ b/docs/55-logging/01-overview.md @@ -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()`. diff --git a/docs/55-logging/02-using.md b/docs/55-logging/02-using.md new file mode 100644 index 0000000..98f8de7 --- /dev/null +++ b/docs/55-logging/02-using.md @@ -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()`. +- [ ] Уровень логирования соответствует окружению. +- [ ] Логи не содержат чувствительных данных. diff --git a/docs/55-logging/03-auto-logging.md b/docs/55-logging/03-auto-logging.md new file mode 100644 index 0000000..b7d8e4b --- /dev/null +++ b/docs/55-logging/03-auto-logging.md @@ -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-запросы. +- При анализе проблем **начинайте с автоматических логов** — они формируются всегда и имеют единый + формат. diff --git a/docs/55-logging/04-manual-logs.md b/docs/55-logging/04-manual-logs.md new file mode 100644 index 0000000..cac5843 --- /dev/null +++ b/docs/55-logging/04-manual-logs.md @@ -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`. + +### Длительные процессы + +Для долгих операций допускается логирование **двух фаз**: + +- начало — ` 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). +- [ ] Отсутствуют конфиденциальные данные. diff --git a/docs/55-logging/05-testing.md b/docs/55-logging/05-testing.md new file mode 100644 index 0000000..bcea4ef --- /dev/null +++ b/docs/55-logging/05-testing.md @@ -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`. diff --git a/docs/55-logging/_category_.yml b/docs/55-logging/_category_.yml new file mode 100644 index 0000000..0966109 --- /dev/null +++ b/docs/55-logging/_category_.yml @@ -0,0 +1 @@ +label: 'Логирование' diff --git a/yarn.lock b/yarn.lock index 454bb21..ed5684a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3202,6 +3202,11 @@ "@types/esquery" "^1.5.0" esquery "^1.5.0" +"@pinojs/redact@^0.4.0": + version "0.4.0" + resolved "https://registry.yarnpkg.com/@pinojs/redact/-/redact-0.4.0.tgz#c3de060dd12640dcc838516aa2a6803cc7b2e9d6" + integrity sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg== + "@pkgjs/parseargs@^0.11.0": version "0.11.0" resolved "https://registry.yarnpkg.com/@pkgjs/parseargs/-/parseargs-0.11.0.tgz#a77ea742fab25775145434eb1d2328cf5013ac33" @@ -5333,6 +5338,11 @@ at-least-node@^1.0.0: resolved "https://registry.yarnpkg.com/at-least-node/-/at-least-node-1.0.0.tgz#602cd4b46e844ad4effc92a8011a3c46e0238dc2" integrity sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg== +atomic-sleep@^1.0.0: + version "1.0.0" + resolved "https://registry.yarnpkg.com/atomic-sleep/-/atomic-sleep-1.0.0.tgz#eb85b77a601fc932cfe432c5acd364a9e2c9075b" + integrity sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ== + autoprefixer@^10.4.13, autoprefixer@^10.4.9: version "10.4.27" resolved "https://registry.yarnpkg.com/autoprefixer/-/autoprefixer-10.4.27.tgz#51ea301a5c3c5f8642f8e564759c4f573be486f2" @@ -6063,7 +6073,7 @@ colord@^2.9.3: resolved "https://registry.yarnpkg.com/colord/-/colord-2.9.3.tgz#4f8ce919de456f1d5c1c368c307fe20f3e59fb43" integrity sha512-jeC1axXpnb0/2nn/Y1LPuLdgXBLH7aDcHu4KEKfqw3CUhX7ZpfBSlPKyqXE6btIgEzfWtrX3/tyBCaCvXvMkOw== -colorette@^2.0.10, colorette@^2.0.14, colorette@^2.0.20: +colorette@^2.0.10, colorette@^2.0.14, colorette@^2.0.20, colorette@^2.0.7: version "2.0.20" resolved "https://registry.yarnpkg.com/colorette/-/colorette-2.0.20.tgz#9eb793e6833067f7235902fcd3b09917a000a95a" integrity sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w== @@ -6557,6 +6567,11 @@ date-format@^4.0.14: resolved "https://registry.yarnpkg.com/date-format/-/date-format-4.0.14.tgz#7a8e584434fb169a521c8b7aa481f355810d9400" integrity sha512-39BOQLs9ZjKh0/patS9nrT8wc3ioX3/eA/zgbKNopnF2wCqJEoxywwwElATYvRsXdnOxA/OQeQoFZ3rFjVajhg== +dateformat@^4.6.3: + version "4.6.3" + resolved "https://registry.yarnpkg.com/dateformat/-/dateformat-4.6.3.tgz#556fa6497e5217fedb78821424f8a1c22fa3f4b5" + integrity sha512-2P0p0pFGzHS5EMnhdxQi7aJN+iMheud0UhG4dlE1DLAlvL8JHjJJTX/CSm4JXwV0Ka5nGk3zC5mcb5bUQUxxMA== + dayjs@^1.11.21: version "1.11.23" resolved "https://registry.yarnpkg.com/dayjs/-/dayjs-1.11.23.tgz#b0a363506dde5f36cf5075e42ebe8115165a8c79" @@ -6890,7 +6905,7 @@ encoding@^0.1.13: dependencies: iconv-lite "^0.6.2" -end-of-stream@^1.4.1: +end-of-stream@^1.1.0, end-of-stream@^1.4.1: version "1.4.5" resolved "https://registry.yarnpkg.com/end-of-stream/-/end-of-stream-1.4.5.tgz#7344d711dea40e0b74abc2ed49778743ccedb08c" integrity sha512-ooEGc6HP26xXq/N+GCGOT0JKCLDGrq2bQUZrQ7gyrJiZANJ/8YDTxTpQBXGMn+WbIQXNVpyWymm7KYVICQnyOg== @@ -7568,6 +7583,11 @@ ext-name@^5.0.0: ext-list "^2.0.0" sort-keys-length "^1.0.0" +fast-copy@^4.0.0: + version "4.3.1" + resolved "https://registry.yarnpkg.com/fast-copy/-/fast-copy-4.3.1.tgz#7ba6022c1827a50a5f8f968d1d99bba2c7b6921e" + integrity sha512-CRzQaTFOFUs6PuhsAq7lk9Zqr995soJBcFNZlfJS/5keTSl1awREV9dZW4xS2nX4pWbhIIR0xp4h+J8PQxCkvg== + fast-deep-equal@^3.1.1, fast-deep-equal@^3.1.3: version "3.1.3" resolved "https://registry.yarnpkg.com/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz#3a7d56b559d6cbc3eb512325244e619a65c6c525" @@ -7604,7 +7624,7 @@ fast-levenshtein@^2.0.6: resolved "https://registry.yarnpkg.com/fast-levenshtein/-/fast-levenshtein-2.0.6.tgz#3d8a5c66883a16a30ca8643e851f19baa7797917" integrity sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw== -fast-safe-stringify@2.1.1: +fast-safe-stringify@2.1.1, fast-safe-stringify@^2.1.1: version "2.1.1" resolved "https://registry.yarnpkg.com/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz#c406a83b6e70d9e35ce3b30a81141df30aeba884" integrity sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA== @@ -8326,6 +8346,11 @@ he@^1.2.0: resolved "https://registry.yarnpkg.com/he/-/he-1.2.0.tgz#84ae65fa7eafb165fddb61566ae14baf05664f0f" integrity sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw== +help-me@^5.0.0: + version "5.0.0" + resolved "https://registry.yarnpkg.com/help-me/-/help-me-5.0.0.tgz#b1ebe63b967b74060027c2ac61f9be12d354a6f6" + integrity sha512-7xgomUX6ADmcYzFik0HzAxh/73YlKR9bmFzf51CZwR+b6YtzU2m0u49hQCqV6SvlqIqsaxovfwdvbnsw3b/zpg== + homedir-polyfill@^1.0.1: version "1.0.3" resolved "https://registry.yarnpkg.com/homedir-polyfill/-/homedir-polyfill-1.0.3.tgz#743298cef4e5af3e194161fbadcc2151d3a058e8" @@ -9428,6 +9453,11 @@ jiti@^1.21.7: resolved "https://registry.yarnpkg.com/jiti/-/jiti-1.21.7.tgz#9dd81043424a3d28458b193d965f0d18a2300ba9" integrity sha512-/imKNG4EbWNrVjoNC/1H5/9GFy+tqjGBHCaSsN+P2RnPqjsLmv6UD3Ej+Kj8nBWaRAwyk7kK5ZUc+OEatnTR3A== +joycon@^3.1.1: + version "3.1.1" + resolved "https://registry.yarnpkg.com/joycon/-/joycon-3.1.1.tgz#bce8596d6ae808f8b68168f5fc69280996894f03" + integrity sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw== + js-tokens@^10.0.0: version "10.0.0" resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-10.0.0.tgz#dffe7599b4a8bb7fe30aff8d0235234dffb79831" @@ -10290,6 +10320,11 @@ neo-async@^2.6.2: resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.2.tgz#b4aafb93e3aeb2d8174ca53cf163ab7d7308305f" integrity sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw== +nestjs-pino@^4.4.1: + version "4.6.1" + resolved "https://registry.yarnpkg.com/nestjs-pino/-/nestjs-pino-4.6.1.tgz#6547c4488566f6d83dcd590863413a37b15f9a47" + integrity sha512-nuARXa0xpdJ1lY2+fgycIQr6H3g0VgqAWNK3xMYjOFcj2DoPETNXj0lV3Y86nRuI7BUfQp5PGiVoZvT4dTWbpQ== + nice-try@^1.0.4: version "1.0.5" resolved "https://registry.yarnpkg.com/nice-try/-/nice-try-1.0.5.tgz#a3378a7696ce7d223e88fc9b764bd7ef1089e366" @@ -10539,6 +10574,11 @@ obug@^2.1.1: resolved "https://registry.yarnpkg.com/obug/-/obug-2.1.1.tgz#2cba74ff241beb77d63055ddf4cd1e9f90b538be" integrity sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ== +on-exit-leak-free@^2.1.0, on-exit-leak-free@^2.1.2: + version "2.1.2" + resolved "https://registry.yarnpkg.com/on-exit-leak-free/-/on-exit-leak-free-2.1.2.tgz#fed195c9ebddb7d9e4c3842f93f281ac8dadd3b8" + integrity sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA== + on-finished@^2.4.1, on-finished@~2.4.1: version "2.4.1" resolved "https://registry.yarnpkg.com/on-finished/-/on-finished-2.4.1.tgz#58c8c44116e54845ad57f14ab10b03533184ac3f" @@ -10551,7 +10591,7 @@ on-headers@~1.1.0: resolved "https://registry.yarnpkg.com/on-headers/-/on-headers-1.1.0.tgz#59da4f91c45f5f989c6e4bcedc5a3b0aed70ff65" integrity sha512-737ZY3yNnXy37FHkQxPzt4UZ2UWPWiCZWLvFZ4fu5cueciegX0zGPnrlY6bwRg4FdQOe9YU8MkmJwGhoMybl8A== -once@^1.3.0, once@^1.4.0: +once@^1.3.0, once@^1.3.1, once@^1.4.0: version "1.4.0" resolved "https://registry.yarnpkg.com/once/-/once-1.4.0.tgz#583b1aa775961d4b113ac17d9c50baef9dd76bd1" integrity sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w== @@ -10984,6 +11024,71 @@ pify@^4.0.1: resolved "https://registry.yarnpkg.com/pify/-/pify-4.0.1.tgz#4b2cd25c50d598735c50292224fd8c6df41e3231" integrity sha512-uB80kBFb/tfd68bVleG9T5GGsGPjJrLAUpR5PZIrhBnIaRTQRjqdJSsIKkOP6OAIFbj7GOrcudc5pNjZ+geV2g== +pino-abstract-transport@^2.0.0: + version "2.0.0" + resolved "https://registry.yarnpkg.com/pino-abstract-transport/-/pino-abstract-transport-2.0.0.tgz#de241578406ac7b8a33ce0d77ae6e8a0b3b68a60" + integrity sha512-F63x5tizV6WCh4R6RHyi2Ml+M70DNRXt/+HANowMflpgGFMAym/VKm6G7ZOQRjqN7XbGxK1Lg9t6ZrtzOaivMw== + dependencies: + split2 "^4.0.0" + +pino-abstract-transport@^3.0.0: + version "3.0.0" + resolved "https://registry.yarnpkg.com/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz#b21e5f33a297e8c4c915c62b3ce5dd4a87a52c23" + integrity sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg== + dependencies: + split2 "^4.0.0" + +pino-http@^10.5.0: + version "10.5.0" + resolved "https://registry.yarnpkg.com/pino-http/-/pino-http-10.5.0.tgz#6a4fd8df93a181fc89f7f89979b8a2146aad29f2" + integrity sha512-hD91XjgaKkSsdn8P7LaebrNzhGTdB086W3pyPihX0EzGPjq5uBJBXo4N5guqNaK6mUjg9aubMF7wDViYek9dRA== + dependencies: + get-caller-file "^2.0.5" + pino "^9.0.0" + pino-std-serializers "^7.0.0" + process-warning "^5.0.0" + +pino-pretty@^13.1.1: + version "13.2.0" + resolved "https://registry.yarnpkg.com/pino-pretty/-/pino-pretty-13.2.0.tgz#3598d57af318518398ba2a8c6903452a8b7575ce" + integrity sha512-jjghD1ML+Di/WxjJDz6j6Y4FT7hIXOlb8h27AyJ+ohtAXJXH4PS/xkv7si+RCCIW59HMgZsMKTDgzdr0RhuRrg== + dependencies: + colorette "^2.0.7" + dateformat "^4.6.3" + fast-copy "^4.0.0" + fast-safe-stringify "^2.1.1" + help-me "^5.0.0" + joycon "^3.1.1" + minimist "^1.2.6" + on-exit-leak-free "^2.1.2" + pino-abstract-transport "^3.0.0" + pump "^3.0.3" + secure-json-parse "^4.1.0" + sonic-boom "^5.0.0" + strip-json-comments "^5.0.3" + +pino-std-serializers@^7.0.0: + version "7.1.0" + resolved "https://registry.yarnpkg.com/pino-std-serializers/-/pino-std-serializers-7.1.0.tgz#a7b0cd65225f29e92540e7853bd73b07479893fc" + integrity sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw== + +pino@^9.0.0, pino@^9.11.0: + version "9.14.0" + resolved "https://registry.yarnpkg.com/pino/-/pino-9.14.0.tgz#673d9711c2d1e64d18670c1ec05ef7ba14562556" + integrity sha512-8OEwKp5juEvb/MjpIc4hjqfgCNysrS94RIOMXYvpYCdm/jglrKEiAYmiumbmGhCvs+IcInsphYDFwqrjr7398w== + dependencies: + "@pinojs/redact" "^0.4.0" + atomic-sleep "^1.0.0" + on-exit-leak-free "^2.1.0" + pino-abstract-transport "^2.0.0" + pino-std-serializers "^7.0.0" + process-warning "^5.0.0" + quick-format-unescaped "^4.0.3" + real-require "^0.2.0" + safe-stable-stringify "^2.3.1" + sonic-boom "^4.0.1" + thread-stream "^3.0.0" + pirates@^4.0.1, pirates@^4.0.7: version "4.0.7" resolved "https://registry.yarnpkg.com/pirates/-/pirates-4.0.7.tgz#643b4a18c4257c8a65104b73f3049ce9a0a15e22" @@ -11463,6 +11568,11 @@ process-nextick-args@~2.0.0: resolved "https://registry.yarnpkg.com/process-nextick-args/-/process-nextick-args-2.0.1.tgz#7820d9b16120cc55ca9ae7792680ae7dba6d7fe2" integrity sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag== +process-warning@^5.0.0: + version "5.1.1" + resolved "https://registry.yarnpkg.com/process-warning/-/process-warning-5.1.1.tgz#9c7f34dd637100966be7d32661831ea328ea776b" + integrity sha512-oCkNVj4OKnKEcocVBcDfiIugN1/cE6rgfT3nCtzeqZPA8+rIxMaQ0xXzIkGP8Gj2qUaP1UR7uhJ1VD8lUCpzCg== + prop-types@^15.8.1: version "15.8.1" resolved "https://registry.yarnpkg.com/prop-types/-/prop-types-15.8.1.tgz#67d87bf1a694f48435cf332c24af10214a3140b5" @@ -11495,6 +11605,14 @@ pseudomap@^1.0.2: resolved "https://registry.yarnpkg.com/pseudomap/-/pseudomap-1.0.2.tgz#f052a28da70e618917ef0a8ac34c1ae5a68286b3" integrity sha512-b/YwNhb8lk1Zz2+bXXpS/LK9OisiZZ1SNsSLxN1x2OXVEhW2Ckr/7mWE5vrC1ZTiJlD9g19jWszTmJsB+oEpFQ== +pump@^3.0.3: + version "3.0.4" + resolved "https://registry.yarnpkg.com/pump/-/pump-3.0.4.tgz#1f313430527fa8b905622ebd22fe1444e757ab3c" + integrity sha512-VS7sjc6KR7e1ukRFhQSY5LM2uBWAUPiOPa/A3mkKmiMwSmRFUITt0xuj+/lesgnCv+dPIEYlkzrcyXgquIHMcA== + dependencies: + end-of-stream "^1.1.0" + once "^1.3.1" + punycode@^2.1.0, punycode@^2.3.1: version "2.3.1" resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.3.1.tgz#027422e2faec0b25e1549c3e1bd8309b9133b6e5" @@ -11543,6 +11661,11 @@ queue-microtask@^1.2.2: resolved "https://registry.yarnpkg.com/queue-microtask/-/queue-microtask-1.2.3.tgz#4929228bbc724dfac43e0efb058caf7b6cfb6243" integrity sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A== +quick-format-unescaped@^4.0.3: + version "4.0.4" + resolved "https://registry.yarnpkg.com/quick-format-unescaped/-/quick-format-unescaped-4.0.4.tgz#93ef6dd8d3453cbc7970dd614fad4c5954d6b5a7" + integrity sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg== + quick-lru@^5.1.1: version "5.1.1" resolved "https://registry.yarnpkg.com/quick-lru/-/quick-lru-5.1.1.tgz#366493e6b3e42a3a6885e2e99d18f80fb7a8c932" @@ -11675,6 +11798,11 @@ readdirp@~3.6.0: dependencies: picomatch "^2.2.1" +real-require@^0.2.0: + version "0.2.0" + resolved "https://registry.yarnpkg.com/real-require/-/real-require-0.2.0.tgz#209632dea1810be2ae063a6ac084fee7e33fba78" + integrity sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg== + rechoir@^0.8.0: version "0.8.0" resolved "https://registry.yarnpkg.com/rechoir/-/rechoir-0.8.0.tgz#49f866e0d32146142da3ad8f0eff352b3215ff22" @@ -12005,6 +12133,11 @@ safe-regex-test@^1.0.3, safe-regex-test@^1.1.0: es-errors "^1.3.0" is-regex "^1.2.1" +safe-stable-stringify@^2.3.1: + version "2.5.0" + resolved "https://registry.yarnpkg.com/safe-stable-stringify/-/safe-stable-stringify-2.5.0.tgz#4ca2f8e385f2831c432a719b108a3bf7af42a1dd" + integrity sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA== + "safer-buffer@>= 2.1.2 < 3", "safer-buffer@>= 2.1.2 < 3.0.0": version "2.1.2" resolved "https://registry.yarnpkg.com/safer-buffer/-/safer-buffer-2.1.2.tgz#44fa161b0187b9549dd84bb91802f9bd8385cd6a" @@ -12195,6 +12328,11 @@ secure-compare@3.0.1: resolved "https://registry.yarnpkg.com/secure-compare/-/secure-compare-3.0.1.tgz#f1a0329b308b221fae37b9974f3d578d0ca999e3" integrity sha512-AckIIV90rPDcBcglUwXPF3kg0P0qmPsPXAj6BBEENQE1p5yA1xfmDJzfi1Tappj37Pv2mVbKpL3Z1T+Nn7k1Qw== +secure-json-parse@^4.1.0: + version "4.1.1" + resolved "https://registry.yarnpkg.com/secure-json-parse/-/secure-json-parse-4.1.1.tgz#065e41f68da3fb4472d01d1b08d290d257070d8f" + integrity sha512-lnd81MQEZKjhW/Gd2TQqdd4XP6QYNdDW/EP+I7nTrFHP9y2LmaGPIHk9xsnzcOiEr1c39c/e84xFgGviQKBTRw== + seek-bzip@^2.0.0: version "2.0.0" resolved "https://registry.yarnpkg.com/seek-bzip/-/seek-bzip-2.0.0.tgz#f0478ab6acd0ac72345d18dc7525dd84d3c706a2" @@ -12515,6 +12653,20 @@ sockjs@^0.3.24: uuid "^8.3.2" websocket-driver "^0.7.4" +sonic-boom@^4.0.1: + version "4.2.1" + resolved "https://registry.yarnpkg.com/sonic-boom/-/sonic-boom-4.2.1.tgz#28598250df4899c0ac572d7e2f0460690ba6a030" + integrity sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q== + dependencies: + atomic-sleep "^1.0.0" + +sonic-boom@^5.0.0: + version "5.0.2" + resolved "https://registry.yarnpkg.com/sonic-boom/-/sonic-boom-5.0.2.tgz#a2ce0c7c70e71f5ef1d5511f67063b0bbaf41705" + integrity sha512-/JEruzo6yhNVhsLblTRchgTQHIt7SsdJP0YyrfWaNKjIOQDfrdZv9gwYraYCAsmKV39/LAdV31FLL5NCDpoL/A== + dependencies: + atomic-sleep "^1.0.0" + sort-keys-length@^1.0.0: version "1.0.1" resolved "https://registry.yarnpkg.com/sort-keys-length/-/sort-keys-length-1.0.1.tgz#9cb6f4f4e9e48155a6aa0671edd336ff1479a188" @@ -12658,7 +12810,7 @@ spdy@^4.0.2: select-hose "^2.0.0" spdy-transport "^3.0.0" -split2@^4.1.0: +split2@^4.0.0, split2@^4.1.0: version "4.2.0" resolved "https://registry.yarnpkg.com/split2/-/split2-4.2.0.tgz#c9c5920904d148bab0b9f67145f245a86aadbfa4" integrity sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg== @@ -12952,6 +13104,11 @@ strip-json-comments@^3.1.1: resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-3.1.1.tgz#31f1281b3832630434831c310c01cccda8cbe006" integrity sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig== +strip-json-comments@^5.0.3: + version "5.0.3" + resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-5.0.3.tgz#b7304249dd402ee67fd518ada993ab3593458bcf" + integrity sha512-1tB5mhVo7U+ETBKNf92xT4hrQa3pm0MZ0PQvuDnWgAAGHDsfp4lPSpiS6psrSiet87wyGPh9ft6wmhOMQ0hDiw== + strtok3@^10.2.0, strtok3@^10.3.4: version "10.3.5" resolved "https://registry.yarnpkg.com/strtok3/-/strtok3-10.3.5.tgz#7213285da0dc3dec0fc8ce5df4b8b7a733f14360" @@ -13338,6 +13495,13 @@ thingies@^2.5.0: resolved "https://registry.yarnpkg.com/thingies/-/thingies-2.6.0.tgz#e09b98b9e6f6caf8a759eca8481fea1de974d2b1" integrity sha512-rMHRjmlFLM1R96UYPvpmnc3LYtdFrT33JIB7L9hetGue1qAPfn1N2LJeEjxUSidu1Iku+haLZXDuEXUHNGO/lg== +thread-stream@^3.0.0: + version "3.2.0" + resolved "https://registry.yarnpkg.com/thread-stream/-/thread-stream-3.2.0.tgz#3720b496d646c8077b57406d53ec5a5385e3938c" + integrity sha512-zLBvqpwr4Esa0kRjcrzGU6zL25lePWaCLMx0RQFrmteozIfeNdaMLpG5U7PeHzvlFkAWaRKA9/KVW4F60iB+qw== + dependencies: + real-require "^0.2.0" + through@^2.3.8: version "2.3.8" resolved "https://registry.yarnpkg.com/through/-/through-2.3.8.tgz#0dd4c9ffaabc357960b1b724115d7e0e86a2e1f5"