[SpringBoot] MDC와 TraceId로 요청 단위 로그 추적하기

문제 상황

 
Spring Boot 애플리케이션에서 로그를 남기다 보면 이런 문제가 발생한다.

• 동시에 여러 요청이 들어옴
• Controller, Service, Repository, Filter, ExceptionHandler에서 로그가 찍힘
• 로그가 서로 섞임

로그인 성공 - memberId=1
회원가입 성공 - memberId=3
닉네임 중복
JWT 인증 성공

 
-> 어떤 요청에서 발생한 로그인지 구분할 수 없음
 
 

해결 전략 - 요청 단위 Trace ID

• 요청마다 고유한 ID를 생성하고 해당 요청에서 발생하는 모든 로그에 동일한 ID를 포함시켜서 해결
• 이를 Correlation ID, TraceId 라고 함
• 스프링에서는 이를 구현하기 위해 MDC를 사용

 

MDC란 무엇인가?

• MDC (Mapped Diagnostic Context)는 SLF4J에서 제공하는 기능
• ThreadLocal 기반 (JVM 내부에 저장됨)
• 현재 스레드에 key-value 데이터 저장
• 로그 패턴에서 %X{key}로 출력 가능

MDC.put("traceId", "abc123");

 
-> 해당 스레드에서 찍히는 로그에 traceId를 자동으로 포함시킬 수 있음
 
 

TraceIdFilter 구현

• OncePerRequestFilter
  • 요청당 한 번만 실행
• MDC.put()
  • 현재 요청 스레드에 traceId 저장
• MDC.clear()
  • 반드시 finally에서 제거 (톰캣 스레드는 재사용되기 때문)

@Component
public class TraceIdFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(
            HttpServletRequest request,
            HttpServletResponse response,
            FilterChain chain
    ) throws ServletException, IOException {

        try {
            String traceId = UUID.randomUUID()
                                 .toString()
                                 .replace("-", "");

            MDC.put("traceId", traceId);

            chain.doFilter(request, response);

        } finally {
            MDC.clear();
        }
    }
}

 
 

로그 패턴 설정

• application.yml에 traceId 출력 설정을 추가

logging:
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] [%X{traceId}] %-5level %logger - %msg%n"

 
-> %X{traceId} 설정이 있어야 MDC에 저장된 traceId가 출력됨
 
 

실제 로그 출력 예시

• 운영 중 특정 에러가 발생했을 때
  • traceId 기준으로 로그 검색
  • 요청 흐름 전체 추적 가능

2026-02-17 12:30:01 [http-nio-8080-exec-1] [a8f3c9e1d4...] INFO  MemberService - 로그인 성공 - memberId=1
2026-02-17 12:30:01 [http-nio-8080-exec-1] [a8f3c9e1d4...] DEBUG JwtFilter - JWT 인증 성공