Структуроване логування

{
  "timestamp": "2026-09-01T10:15:00.000Z",
  "level": "info",
  "context": "UsersService",
  "requestId": "f3c8d3a6-6b2c-4d75-9a3d-83e5a9d5f521",
  "event": "user_loaded",
  "userId": 42
}

import { Injectable } from '@nestjs/common';
import { AsyncLocalStorage } from 'node:async_hooks';

export interface RequestStore {
  requestId: string;
}

@Injectable()
export class RequestContextService {
  private readonly storage = new AsyncLocalStorage<RequestStore>();

  run<T>(store: RequestStore, callback: () => T): T {
    return this.storage.run(store, callback);
  }

  getRequestId(): string | undefined {
    return this.storage.getStore()?.requestId;
  }
}

import { Injectable, LoggerService } from '@nestjs/common';
import { RequestContextService } from './request-context.service';

type LogLevel = 'info' | 'warn' | 'error' | 'debug' | 'verbose';

@Injectable()
export class JsonLoggerService implements LoggerService {
  constructor(
    private readonly requestContext: RequestContextService,
  ) {}

  log(message: unknown, context?: string): void {
    this.write('info', message, context);
  }

  warn(message: unknown, context?: string): void {
    this.write('warn', message, context);
  }

  error(message: unknown, trace?: string, context?: string): void {
    this.write('error', message, context, trace);
  }

  debug(message: unknown, context?: string): void {
    this.write('debug', message, context);
  }

  verbose(message: unknown, context?: string): void {
    this.write('verbose', message, context);
  }

  setContext(): void {
    // Контекст передається другим або третім аргументом методів логера.
  }

  private write(
    level: LogLevel,
    message: unknown,
    context?: string,
    trace?: string,
  ): void {
    const event: Record<string, unknown> = {
      timestamp: new Date().toISOString(),
      level,
    };

    const requestId = this.requestContext.getRequestId();

    if (requestId) {
      event.requestId = requestId;
    }

    if (context) {
      event.context = context;
    }

    if (message instanceof Error) {
      event.message = message.message;
      event.error = {
        name: message.name,
        stack: message.stack,
      };
    } else if (
      typeof message === 'object' &&
      message !== null &&
      !Array.isArray(message)
    ) {
      Object.assign(event, message);
    } else {
      event.message = String(message);
    }

    if (trace) {
      event.trace = trace;
    }

    process.stdout.write(`${JSON.stringify(event)}\n`);
  }
}

this.logger.log(
  {
    event: 'user_loaded',
    userId: 42,
  },
  UsersService.name,
);

{
  "timestamp": "2026-09-01T10:15:00.000Z",
  "level": "info",
  "requestId": "f3c8d3a6-6b2c-4d75-9a3d-83e5a9d5f521",
  "context": "UsersService",
  "event": "user_loaded",
  "userId": 42
}

import {
  Injectable,
  Logger,
  NestMiddleware,
} from '@nestjs/common';
import { randomUUID } from 'node:crypto';
import { Request, Response, NextFunction } from 'express';
import { RequestContextService } from './request-context.service';

@Injectable()
export class RequestLoggingMiddleware implements NestMiddleware {
  private readonly logger = new Logger(
    RequestLoggingMiddleware.name,
  );

  constructor(
    private readonly requestContext: RequestContextService,
  ) {}

  use(
    request: Request,
    response: Response,
    next: NextFunction,
  ): void {
    const requestId =
      this.getRequestId(request) ?? randomUUID();

    const startedAt = Date.now();

    response.setHeader('x-request-id', requestId);

    this.requestContext.run({ requestId }, () => {
      response.on('finish', () => {
        this.logger.log({
          event: 'http_request_completed',
          method: request.method,
          path: request.originalUrl ?? request.url,
          statusCode: response.statusCode,
          durationMs: Date.now() - startedAt,
        });
      });

      next();
    });
  }

  private getRequestId(request: Request): string | undefined {
    const value = request.header('x-request-id');

    if (!value || value.length > 100) {
      return undefined;
    }

    return value;
  }
}

import {
  MiddlewareConsumer,
  Module,
  NestModule,
} from '@nestjs/common';
import { AppController } from './app.controller';
import { JsonLoggerService } from './json-logger.service';
import { RequestContextService } from './request-context.service';
import { RequestLoggingMiddleware } from './request-logging.middleware';

@Module({
  controllers: [AppController],
  providers: [
    JsonLoggerService,
    RequestContextService,
  ],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    consumer
      .apply(RequestLoggingMiddleware)
      .forRoutes('*');
  }
}

import { Logger } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { JsonLoggerService } from './json-logger.service';

async function bootstrap(): Promise<void> {
  const app = await NestFactory.create(AppModule, {
    bufferLogs: true,
  });

  const jsonLogger = app.get(JsonLoggerService);

  app.useLogger(jsonLogger);
  app.enableShutdownHooks();

  await app.listen(3000);

  new Logger('Bootstrap').log({
    event: 'application_started',
    port: 3000,
  });
}

void bootstrap();

import { Controller, Get, Logger } from '@nestjs/common';

@Controller()
export class AppController {
  private readonly logger = new Logger(AppController.name);

  @Get('health')
  getHealth(): { status: string } {
    this.logger.log({
      event: 'health_check',
      status: 'ok',
    });

    return {
      status: 'ok',
    };
  }
}

{
  "timestamp": "2026-09-01T10:15:00.000Z",
  "level": "info",
  "requestId": "f3c8d3a6-6b2c-4d75-9a3d-83e5a9d5f521",
  "context": "AppController",
  "event": "health_check",
  "status": "ok"
}

{
  "timestamp": "2026-09-01T10:15:00.010Z",
  "level": "info",
  "requestId": "f3c8d3a6-6b2c-4d75-9a3d-83e5a9d5f521",
  "context": "RequestLoggingMiddleware",
  "event": "http_request_completed",
  "method": "GET",
  "path": "/health",
  "statusCode": 200,
  "durationMs": 10
}

this.logger.warn({
  event: 'rate_limit_near',
  userId,
  remainingRequests: 2,
});

this.logger.error(
  {
    event: 'payment_failed',
    paymentId,
    reason: 'provider_timeout',
  },
  undefined,
  'PaymentsService',
);

cat application.log | jq 'select(.event == "http_request_completed") | {requestId, statusCode, durationMs}'

cat application.log | jq 'select(.level == "error")'

cat application.log | jq 'select(.requestId == "f3c8d3a6-6b2c-4d75-9a3d-83e5a9d5f521")'

this.logger.log({
  event: 'order_created',
  orderId,
  userId,
});

this.logger.log(`Замовлення ${orderId} створено користувачем ${userId}`);

this.logger.log({
  event: 'user_loaded',
  userId: user.id,
  durationMs,
});

this.logger.log(JSON.stringify({
  event: 'user_loaded',
  userId: 42,
}));