로깅과 감사 추적

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

@Injectable()
export class AppService {
  private readonly logger = new Logger(AppService.name);

  getHello(requestId: string): string {
    // 메시지 뒤의 객체는 같은 로그 레코드의 구조화된 params가 됩니다.
    this.logger.log('인사말을 반환했습니다.', {
      event: 'greeting.requested',
      requestId,
      resource: 'GET /',
      outcome: 'SUCCEEDED',
    });

    return 'Hello World!';
  }
}

import { ConsoleLogger } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap(): Promise<void> {
  const logger = new ConsoleLogger({
    json: true,
    colors: false,
    logLevels: ['fatal', 'error', 'warn', 'log'],
  });

  const app = await NestFactory.create(AppModule, {
    logger,
  });

  await app.listen(process.env.PORT ?? 3000);
}

void bootstrap();

import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';
import { Injectable, NestMiddleware } from '@nestjs/common';
import type { NextFunction, Request, Response } from 'express';

interface RequestContext {
  readonly requestId: string;
}

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

  run(context: RequestContext, next: () => void): void {
    this.storage.run(context, next);
  }

  get(): RequestContext | undefined {
    return this.storage.getStore();
  }
}

@Injectable()
export class RequestContextMiddleware implements NestMiddleware {
  constructor(private readonly context: RequestContextStore) {}

  use(request: Request, response: Response, next: NextFunction): void {
    const requestId = randomUUID();
    response.setHeader('x-request-id', requestId);
    this.context.run({ requestId }, next);
  }
}

npm install winston

import { Injectable, LoggerService } from '@nestjs/common';
import { createLogger, format, transports } from 'winston';
import { RequestContextStore } from './request-context';

const nestLevels = {
  fatal: 0,
  error: 1,
  warn: 2,
  log: 3,
  debug: 4,
  verbose: 5,
} as const;

type NestLevel = keyof typeof nestLevels;

function readLogLevel(value: string | undefined): NestLevel {
  if (value === undefined) return 'log';
  if (!Object.hasOwn(nestLevels, value)) throw new Error(`Invalid LOG_LEVEL: ${value}`);
  return value as NestLevel;
}

function isStack(value: unknown): value is string {
  return typeof value === 'string' && /^(.)+\n\s+at .+:\d+:\d+/.test(value);
}

function splitOptionalParams(level: NestLevel, optionalParams: unknown[]) {
  const params = [...optionalParams];
  let context: string | undefined;
  let stack: string | undefined;

  if (level === 'error') {
    const last = params.at(-1);
    if (isStack(last)) {
      stack = params.pop() as string;
    } else if (typeof last === 'string') {
      context = params.pop() as string;
      const stackCandidate = params.at(-1);
      if (isStack(stackCandidate)) stack = params.pop() as string;
    }
  } else if (typeof params.at(-1) === 'string') {
    context = params.pop() as string;
  }

  return { context, stack, params };
}

// Winston의 log(entry)는 문자열 message가 있는 객체를 받습니다.
type SafeRecord = { event: string; message: string; [key: string]: unknown };

function toSafeRecord(message: unknown): SafeRecord {
  if (message instanceof Error) {
    return {
      event: 'application.error',
      message: message.message,
      error: {
        name: message.name,
        message: message.message,
        stack: message.stack,
      },
    };
  }

  if (typeof message === 'string') {
    return { event: 'application.message', message };
  }

  const value = message && typeof message === 'object'
    ? message as Record<string, unknown>
    : {};

  // 객체 전체를 펼치지 않고 승인된 필드만 복사합니다.
  return {
    event: typeof value.event === 'string' ? value.event : 'application.event',
    message: typeof value.message === 'string' ? value.message : '구조화 이벤트',
    resource: typeof value.resource === 'string' ? value.resource : undefined,
    outcome: typeof value.outcome === 'string' ? value.outcome : undefined,
    durationMs: typeof value.durationMs === 'number' ? value.durationMs : undefined,
  };
}

function toSafeParam(value: unknown): unknown {
  if (value instanceof Error || (value !== null && typeof value === 'object')) {
    return toSafeRecord(value);
  }
  if (typeof value === 'bigint') return value.toString();
  if (typeof value === 'function' || typeof value === 'symbol') return String(value);
  return value;
}

@Injectable()
export class WinstonLogger implements LoggerService {
  private readonly logger = createLogger({
    levels: nestLevels,
    level: readLogLevel(process.env.LOG_LEVEL),
    defaultMeta: { service: 'user-api' },
    format: format.combine(
      format.timestamp(),
      format.errors({ stack: true }),
      format.json(),
    ),
    transports: [new transports.Console()],
    exceptionHandlers: [new transports.Console()],
    rejectionHandlers: [new transports.Console()],
    exitOnError: true,
  });

  constructor(private readonly requestContext: RequestContextStore) {}

  log(message: any, ...optionalParams: any[]): void {
    this.write('log', message, optionalParams);
  }

  fatal(message: any, ...optionalParams: any[]): void {
    this.write('fatal', message, optionalParams);
  }

  error(message: any, ...optionalParams: any[]): void {
    this.write('error', message, optionalParams);
  }

  warn(message: any, ...optionalParams: any[]): void {
    this.write('warn', message, optionalParams);
  }

  debug(message: any, ...optionalParams: any[]): void {
    this.write('debug', message, optionalParams);
  }

  verbose(message: any, ...optionalParams: any[]): void {
    this.write('verbose', message, optionalParams);
  }

  private write(level: NestLevel, message: unknown, optionalParams: unknown[]): void {
    const { context, stack, params } = splitOptionalParams(level, optionalParams);

    this.logger.log({
      level,
      ...toSafeRecord(message),
      ...this.requestContext.get(),
      context,
      errorStack: stack,
      params: params.filter((value) => value !== undefined).map(toSafeParam),
    });
  }
}

import {
  MiddlewareConsumer,
  Module,
  NestModule,
  RequestMethod,
} from '@nestjs/common';
import {
  RequestContextMiddleware,
  RequestContextStore,
} from './request-context';
import { WinstonLogger } from './winston.logger';

@Module({
  providers: [RequestContextStore, WinstonLogger],
  exports: [WinstonLogger],
})
export class LoggingModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    consumer
      .apply(RequestContextMiddleware)
      .forRoutes({ path: '/{*path}', method: RequestMethod.ALL });
  }
}

import { LoggingModule } from './logging/logging.module';

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { WinstonLogger } from './logging/winston.logger';

async function bootstrap(): Promise<void> {
  const app = await NestFactory.create(AppModule, { bufferLogs: true });
  app.useLogger(app.get(WinstonLogger));
  await app.listen(process.env.PORT ?? 3000);
}

void bootstrap();

import { Column, CreateDateColumn, Entity, PrimaryColumn } from 'typeorm';

@Entity('audit_outbox')
export class AuditOutbox {
  @PrimaryColumn('uuid')
  eventId!: string;

  @Column({ type: 'timestamptz' })
  occurredAt!: Date;

  @CreateDateColumn({ type: 'timestamptz' })
  recordedAt!: Date;

  @Column()
  actorType!: string;

  @Column()
  actorId!: string;

  @Column()
  action!: string;

  @Column()
  resourceType!: string;

  @Column()
  resourceId!: string;

  @Column()
  outcome!: string;

  @Column()
  requestId!: string;

  @Column({ nullable: true })
  traceId?: string;

  @Column({ type: 'jsonb' })
  changes!: { fields: string[] };
}

import { randomUUID } from 'node:crypto';
import { Injectable } from '@nestjs/common';
import { DataSource } from 'typeorm';
import { AuditOutbox } from '../audit/audit-outbox.entity';
import { User } from './user.entity';

interface AuditActor {
  type: 'USER' | 'SERVICE' | 'ADMIN';
  id: string;
}

@Injectable()
export class UsersService {
  constructor(private readonly dataSource: DataSource) {}

  async createUser(
    actor: AuditActor,
    input: Pick<User, 'email'>,
    requestId: string,
    traceId?: string,
  ): Promise<User> {
    return this.dataSource.transaction(async (manager) => {
      const user = await manager.save(User, manager.create(User, input));

      await manager.insert(AuditOutbox, {
        eventId: randomUUID(),
        occurredAt: new Date(),
        actorType: actor.type,
        actorId: actor.id,
        action: 'USER_CREATED',
        resourceType: 'User',
        resourceId: String(user.id),
        outcome: 'SUCCEEDED',
        requestId,
        traceId,
        changes: { fields: ['email'] },
      });

      return user;
    });
  }
}