로그 속에 숨은 사용자 찾기: Spring Boot JSON 로깅과 MDC 전략
단순한 텍스트 로그로는 복잡한 마이크로서비스 환경의 장애를 잡을 수 없습니다. 사용자 ID와 세션 정보를 JSON 구조로 기록해 추적 가능성을 극대화하는 실무 전략을 공개합니다.
서비스 규모가 커지고 트래픽이 몰리기 시작하면, 개발자가 가장 먼저 마주하는 벽은 ‘로그의 홍수’입니다. 수만 줄의 텍스트 로그 사이에서 특정 사용자가 겪은 오류를 찾기 위해 grep 명령어를 치고 있지만, 정작 필요한 것은 ‘이 요청이 어떤 사용자의 어떤 세션에서 시작되어 어디까지 흘러갔는가’에 대한 명확한 연결 고리입니다. 단순한 텍스트 기반의 로깅은 사람이 읽기에는 편할지 모르나, 기계가 분석하기에는 최악의 형태입니다.
현대적인 백엔드 아키텍처, 특히 마이크로서비스 아키텍처(MSA)에서는 로그 자체가 하나의 데이터셋이 되어야 합니다. 로그를 단순히 ‘기록’하는 수준을 넘어 ‘쿼리’할 수 있는 형태로 만드는 것이 핵심입니다. 이를 위해 필요한 것이 바로 구조화된 로깅(Structured Logging)과 MDC(Mapped Diagnostic Context)를 활용한 컨텍스트 추적입니다.
왜 텍스트 로그를 버리고 JSON을 선택해야 하는가
전통적인 로그 파일은 날짜, 로그 레벨, 클래스명, 메시지가 한 줄로 이어지는 형태입니다. 하지만 운영 환경에서 ELK(Elasticsearch, Logstash, Kibana)나 Grafana Loki 같은 로그 분석 플랫폼을 사용한다면 이야기가 달라집니다. JSON 형식의 로그는 각 필드가 명확히 구분되어 있어, 별도의 복잡한 파싱 규칙(Grok pattern) 없이도 즉시 인덱싱이 가능합니다.
예를 들어, userId라는 필드가 JSON으로 정의되어 있다면, 수백만 건의 로그 중에서 특정 사용자의 활동 내역만 0.1초 만에 필터링할 수 있습니다. 이는 장애 대응 시간을 획기적으로 줄여주며, 비즈니스 지표 분석을 위한 기초 데이터로도 활용될 수 있게 합니다.
MDC: 로그에 ‘맥락’을 입히는 마법
Spring Boot 환경에서 사용자 ID나 세션 ID를 모든 로그 메서드에 인자로 전달하는 것은 불가능에 가깝습니다. 코드의 가독성을 해칠 뿐만 아니라 유지보수 비용이 기하급수적으로 증가하기 때문입니다. 이때 구원투수로 등장하는 것이 SLF4J의 MDC입니다.
MDC는 내부적으로 ThreadLocal을 사용하여 현재 실행 중인 스레드에 특정 값을 저장합니다. 한 번 저장된 값은 해당 스레드가 종료되거나 명시적으로 삭제하기 전까지 모든 로그 출력 시 자동으로 포함됩니다. 즉, 필터나 인터셉터 단계에서 사용자 정보를 MDC에 넣어두기만 하면, 서비스 레이어와 리포지토리 레이어에서 남기는 모든 로그에 사용자 ID가 자동으로 찍히게 됩니다.
기술적 구현: JSON 로깅과 사용자 추적 설정
Spring Boot에서 이를 구현하기 위해서는 logback-spring.xml 설정과 HandlerInterceptor 혹은 Filter 구현이 필요합니다. 가장 효율적인 흐름은 다음과 같습니다.
- Logback JSON Encoder 설정:
logstash-logback-encoder라이브러리를 추가하여 로그 출력 형식을 JSON으로 변경합니다. 이를 통해 표준 출력(Console)이나 파일에 기록되는 로그가 JSON 객체 형태로 출력됩니다. - Context Filter 구현: HTTP 요청이 들어오는 진입점에서 JWT 토큰이나 세션에서 사용자 식별자(User ID)와 요청 고유 ID(Trace ID)를 추출합니다.
- MDC 주입: 추출한 정보를
MDC.put("userId", userId)와 같이 저장합니다. - 자원 해제: 요청 처리가 끝나는 시점에
MDC.clear()를 호출하여 스레드 풀을 사용하는 환경에서 데이터 오염(Memory Leak 및 엉뚱한 사용자 정보 출력)을 방지합니다.
구조화 로깅 도입의 득과 실
모든 기술적 선택에는 트레이드오프가 존재합니다. JSON 로깅과 MDC 도입 시 고려해야 할 장단점은 다음과 같습니다.
| 구분 | 장점 (Pros) | 단점 (Cons) |
|---|---|---|
| 분석 효율성 | 특정 사용자/세션별 정밀 쿼리 가능, 대시보드 시각화 용이 | 사람이 직접 raw 로그 파일을 읽을 때 가독성 저하 |
| 운영 편의성 | 분산 환경에서 요청의 흐름(Trace) 추적 가능 | 로그 데이터의 크기가 증가하여 저장 비용 상승 |
| 개발 생산성 | 로그 메서드에 일일이 파라미터를 넘길 필요 없음 | 비동기 처리(Async) 시 MDC 컨텍스트 전파 설정 필요 |
실무 적용 사례: 결제 실패 원인 분석
실제 커머스 서비스에서 발생한 결제 실패 장애 사례를 들어보겠습니다. 기존 텍스트 로그 환경에서는 ‘결제 API 호출 실패’라는 로그는 많았지만, 이것이 특정 카드사의 문제인지, 특정 사용자의 계정 문제인지, 아니면 간헐적인 네트워크 타임아웃인지 구분하기 위해 수많은 로그를 대조해야 했습니다.
하지만 JSON 로깅과 MDC를 도입한 후에는 상황이 바뀌었습니다. Kibana에서 level: "ERROR" AND message: "Payment Failed"로 검색한 뒤, 결과로 나온 로그들의 userId 필드를 그룹화했습니다. 그 결과, 특정 OS 버전의 사용자들에게서만 집중적으로 오류가 발생하고 있음을 단 5분 만에 찾아낼 수 있었습니다. 로그가 단순한 기록이 아니라 ‘분석 가능한 데이터’가 되었을 때 발휘되는 힘입니다.
주의사항: 비동기 환경에서의 컨텍스트 유실
많은 개발자가 MDC를 도입하고 당황하는 지점이 바로 @Async나 CompletableFuture를 사용할 때입니다. MDC는 ThreadLocal 기반이므로, 새로운 스레드가 생성되면 기존 스레드의 MDC 값은 복사되지 않습니다. 이로 인해 비동기 로직에서 찍히는 로그에는 사용자 ID가 누락되는 현상이 발생합니다.
이를 해결하기 위해서는 TaskDecorator를 구현하여 메인 스레드의 MDC 컨텍스트를 비동기 스레드로 복사해주는 설정이 반드시 필요합니다. 이 과정을 생략하면 구조화 로깅의 가장 큰 장점인 ‘추적 가능성’이 비동기 구간에서 끊기게 됩니다.
지금 당장 실행할 수 있는 액션 아이템
완벽한 시스템을 한 번에 구축하려 하기보다, 단계적으로 접근하는 것을 권장합니다. 실무자라면 다음 순서로 적용해 보십시오.
- 1단계:
logstash-logback-encoder를 추가하여 로컬 환경에서 로그가 JSON으로 출력되는지 확인하십시오. - 2단계:
OncePerRequestFilter를 생성하여 모든 요청에traceId(UUID)를 생성하고 MDC에 저장하십시오. 사용자 ID가 없더라도 요청마다 고유 ID가 있으면 추적이 훨씬 쉬워집니다. - 3단계: 인증 필터 단계에서
userId를 MDC에 추가하고, 로그 분석 툴(ELK, Loki 등)에서 해당 필드로 필터링하는 쿼리를 작성해 보십시오. - 4단계: 비동기 로직을 사용 중이라면
TaskDecorator를 통해 컨텍스트 전파 설정을 완료하십시오.
로그는 시스템이 개발자에게 보내는 유일한 구조 신호입니다. 그 신호를 단순한 텍스트 뭉치로 남겨둘 것인지, 아니면 정교하게 설계된 데이터로 변환하여 빠르게 문제를 해결할 열쇠로 만들 것인지는 여러분의 선택에 달려 있습니다. 구조화된 로깅은 단순한 설정의 변경이 아니라, 운영 철학의 변화입니다.
FAQ
Spring Boot Json Logging With User And Session의 핵심 쟁점은 무엇인가요?
핵심 문제 정의, 비용 구조, 실제 적용 방법, 리스크를 함께 봐야 합니다.
Spring Boot Json Logging With User And Session를 바로 도입해도 되나요?
작은 범위에서 실험하고 데이터를 확인한 뒤 단계적으로 확대하는 편이 안전합니다.
실무에서 가장 먼저 확인할 것은 무엇인가요?
목표 지표, 대상 사용자, 예산 범위, 운영 책임자를 먼저 명확히 해야 합니다.
법률이나 정책 이슈도 함께 봐야 하나요?
네. 데이터 수집 방식, 플랫폼 정책, 개인정보 관련 제한을 반드시 점검해야 합니다.
성과를 어떻게 측정하면 좋나요?
비용, 전환율, 클릭률, 운영 공수, 재사용 가능성 같은 지표를 함께 보는 것이 좋습니다.
관련 글 추천
- https://infobuza.com/2026/06/01/20260601-c0x1ct/
- https://infobuza.com/2026/06/01/20260601-2v92s7/
지금 바로 시작할 수 있는 실무 액션
- 현재 팀의 AI 활용 범위와 검증 절차를 먼저 문서화합니다.
- 작은 파일럿 프로젝트로 KPI를 정하고 2~4주 단위로 검증합니다.
- 보안, 품질, 리뷰 기준을 자동화 도구와 함께 연결합니다.
