refactor: 에러 로그 개선 및 액세스 로그 추가

Author: ooheunda

src/app.ts

@@ -14,6 +14,7 @@ import { options } from '@/configs/swagger.config';
 import { getSentryStatus } from '@/configs/sentry.config';
 import { getCacheStatus } from '@/configs/cache.config';
 import { errorHandlingMiddleware } from '@/middlewares/errorHandling.middleware';
+import { accessLogMiddleware } from '@/middlewares/accessLog.middleware';
 
 dotenv.config();
 
@@ -24,6 +25,7 @@ app.set('trust proxy', process.env.NODE_ENV === 'production');
 
 const swaggerSpec = swaggerJSDoc(options);
 
+app.use(accessLogMiddleware);
 app.use(cookieParser());
 app.use(express.json({ limit: '10mb' })); // 파일 업로드 대비
 app.use(express.urlencoded({ extended: true, limit: '10mb' }));

src/configs/logger.config.ts

@@ -13,6 +13,16 @@ if (!fs.existsSync(errorLogDir)) {
 }
 
 const jsonFormat = winston.format.printf((info) => {
+  // info.message가 객체인 경우
+  if (typeof info.message === 'object' && info.message !== null) {
+    return JSON.stringify({
+      timestamp: info.timestamp,
+      level: info.level.toUpperCase(),
+      logger: info.logger || 'default',
+      ...info.message, // 로그 데이터 평탄화
+    });
+  }
+
   return JSON.stringify({
     timestamp: info.timestamp,
     level: info.level.toUpperCase(),

src/middlewares/accessLog.middleware.ts

@@ -0,0 +1,21 @@
+import { Request, Response, NextFunction } from 'express';
+import { recordRequestStart, logAccess } from '@/utils/logging.util';
+
+/**
+ * 액세스 로그 미들웨어
+ * 모든 요청의 시작과 끝을 기록합니다.
+ */
+export const accessLogMiddleware = (req: Request, res: Response, next: NextFunction): void => {
+  // 요청 시작 시점 기록
+  recordRequestStart(req);
+
+  // 응답 완료 시 액세스 로그 기록
+  res.on('finish', () => {
+    if (res.statusCode < 400) {
+      // 400 이상은 에러 로그로 처리
+      logAccess(req, res);
+    }
+  });
+
+  next();
+};

src/middlewares/errorHandling.middleware.ts

@@ -2,7 +2,7 @@
 import { Request, Response, NextFunction, ErrorRequestHandler } from 'express';
 import { CustomError } from '@/exception';
 import * as Sentry from '@sentry/node';
-import logger from '@/configs/logger.config';
+import { logError } from '@/utils/logging.util';
 
 export const errorHandlingMiddleware: ErrorRequestHandler = (
   err: CustomError,
@@ -11,16 +11,20 @@ export const errorHandlingMiddleware: ErrorRequestHandler = (
   next: NextFunction,
 ) => {
   if (err instanceof CustomError) {
-    res
-      .status(err.statusCode)
-      .json({ success: false, message: err.message, error: { code: err.code, statusCode: err.statusCode } });
+    res.status(err.statusCode);
+    logError(req, res, err, `Custom Error: ${err.message}`);
+
+    res.json({ success: false, message: err.message, error: { code: err.code, statusCode: err.statusCode } });
     return;
   }
 
+  // Sentry에 에러 전송
   Sentry.captureException(err);
-  logger.error('Internal Server Error');
 
-  res.status(500).json({
+  res.status(500);
+  logError(req, res, err as Error, 'Internal Server Error');
+
+  res.json({
     success: false,
     message: '서버 내부 에러가 발생하였습니다.',
     error: {

src/middlewares/validation.middleware.ts

@@ -2,6 +2,7 @@ import { NextFunction, Request, Response } from 'express';
 import { plainToInstance } from 'class-transformer';
 import { validate } from 'class-validator';
 import logger from '@/configs/logger.config';
+import { BadRequestError } from '@/exception';
 
 type RequestKey = 'body' | 'user' | 'query';
 
@@ -16,16 +17,7 @@ export const validateRequestDto = <T extends object>(
       const errors = await validate(value);
 
       if (errors.length > 0) {
-        logger.error(`API 입력 검증 실패, errors: ${errors}`);
-        res.status(400).json({
-          success: false,
-          message: '검증에 실패하였습니다. 입력값을 다시 확인해주세요.',
-          errors: errors.map((error) => ({
-            property: error.property,
-            constraints: error.constraints,
-          })),
-        });
-        return;
+        throw new BadRequestError(`API 입력 검증 실패, errors: ${errors}`);
       }
 
       req[key] = value as T;

src/types/express.d.ts

@@ -8,6 +8,8 @@ declare global {
         accessToken: string;
         refreshToken: string;
       };
+      requestId: string;
+      startTime: number;
     }
   }
 }

src/types/index.ts

@@ -42,5 +42,8 @@ export { TotalStatsResponseDto } from '@/types/dto/responses/totalStatsResponse.
 export type { SentryIssueStatus } from '@/types/models/Sentry.type';
 export type { SentryProject, SentryIssue, SentryWebhookData } from '@/types/models/Sentry.type';
 
+// Logging 관련
+export type { LogContext, ErrorLogData, AccessLogData } from '@/types/logging';
+
 // Common
 export { EmptyResponseDto } from '@/types/dto/responses/emptyReponse.type';

src/types/logging.ts

@@ -0,0 +1,33 @@
+/**
+ * 기본 로그 컨텍스트 정보
+ */
+export interface LogContext {
+  requestId: string;
+  userId?: string;
+  method: string;
+  url: string;
+  userAgent?: string;
+  ip?: string;
+}
+
+/**
+ * 에러 로그 데이터
+ */
+export interface ErrorLogData extends LogContext {
+  logger: string;
+  message: string;
+  statusCode: number;
+  errorCode?: string;
+  stack?: string;
+  responseTime?: number;
+}
+
+/**
+ * 액세스 로그 데이터
+ */
+export interface AccessLogData extends LogContext {
+  logger: string;
+  statusCode: number;
+  responseTime: number;
+  responseSize?: number;
+}

src/utils/logging.util.ts

@@ -0,0 +1,128 @@
+import { Request, Response } from 'express';
+import { randomUUID } from 'crypto';
+import logger from '@/configs/logger.config';
+import { LogContext, ErrorLogData, AccessLogData } from '@/types/logging';
+import { CustomError } from '@/exception';
+
+/**
+ * 클라이언트 IP 주소 추출
+ */
+export const getClientIp = (req: Request): string => {
+  return (
+    (req.headers['x-forwarded-for'] as string)?.split(',')[0] ||
+    (req.headers['x-real-ip'] as string) ||
+    req.socket.remoteAddress ||
+    'unknown'
+  );
+};
+
+/**
+ * 요청에서 기본 로그 컨텍스트 생성
+ */
+export const createLogContext = (req: Request): LogContext => {
+  return {
+    requestId: req.requestId || randomUUID(),
+    userId: req.user?.velog_uuid,
+    method: req.method,
+    url: req.originalUrl || req.url,
+    userAgent: req.headers['user-agent'],
+    ip: getClientIp(req),
+  };
+};
+
+/**
+ * 로그 레벨과 로거 이름 결정
+ */
+export const getLogLevel = (statusCode: number): 'info' | 'warn' | 'error' => {
+  if (statusCode < 400) return 'info';
+  if (statusCode === 404) return 'warn';
+  return 'error';
+};
+
+/**
+ * 에러 로그 생성 및 출력
+ *
+ * @param req Express Request 객체
+ * @param res Express Response 객체
+ * @param error Error 객체
+ * @param customMessage 커스텀 에러 메시지 (선택)
+ * @param additionalData 추가 로그 데이터 (선택)
+ */
+export const logError = (
+  req: Request,
+  res: Response,
+  error: Error,
+  customMessage?: string,
+  additionalData?: Record<string, unknown>,
+): void => {
+  const statusCode = res.statusCode || 500;
+  const level = getLogLevel(statusCode);
+
+  const context = createLogContext(req);
+  const responseTime = req.startTime ? Date.now() - req.startTime : undefined;
+
+  // 스택 트레이스 포함 여부 결정
+  const includeStack = error instanceof CustomError && error.statusCode < 500 ? false : true;
+
+  // 기본 에러 로그 데이터 생성 (winston 기본 필드 제외)
+  const errorLogData: ErrorLogData = {
+    logger: 'error',
+    requestId: context.requestId,
+    userId: context.userId,
+    method: context.method,
+    url: context.url,
+    userAgent: context.userAgent,
+    ip: context.ip,
+    message: customMessage || error.message,
+    statusCode,
+    errorCode: error instanceof CustomError ? error.code : undefined,
+    ...(includeStack && { stack: error.stack }),
+    responseTime,
+    ...additionalData,
+  };
+
+  logger[level]({ message: errorLogData });
+};
+
+/**
+ * 액세스 로그 생성 및 출력
+ *
+ * @param req Express Request 객체
+ * @param res Express Response 객체
+ * @param additionalData 추가 로그 데이터 (선택)
+ */
+export const logAccess = (req: Request, res: Response, additionalData?: Record<string, unknown>): void => {
+  const statusCode = res.statusCode;
+  const level = getLogLevel(statusCode);
+
+  const context = createLogContext(req);
+  const responseTime = req.startTime ? Date.now() - req.startTime : 0;
+
+  // 응답 크기 추정 (정확하지 않을 수 있음)
+  const contentLength = res.get('content-length');
+  const responseSize = contentLength ? parseInt(contentLength, 10) : undefined;
+
+  const accessLogData: AccessLogData = {
+    logger: 'access',
+    requestId: context.requestId,
+    userId: context.userId,
+    method: context.method,
+    url: context.url,
+    userAgent: context.userAgent,
+    ip: context.ip,
+    statusCode,
+    responseTime,
+    responseSize,
+    ...additionalData,
+  };
+
+  logger[level](accessLogData);
+};
+
+/**
+ * 요청 시작 시점 기록을 위한 미들웨어 헬퍼
+ */
+export const recordRequestStart = (req: Request): void => {
+  req.requestId = req.requestId || randomUUID();
+  req.startTime = Date.now();
+};