작성자: @기중

작성일: 2025-09-24 ~ 2025-09-26

1. 개요

안정적인 서비스 운영 및 개선을 위해 API 요청, 데이터베이스 쿼리에 대한 상세한 로그를 기록하는 시스템을 구축합니다. 본 문서는 해당 로깅 시스템의 요구사항, 이를 충족하기 위해 선택한 기술 스택, 그리고 핵심 구현 방식에 대해 기술합니다.

2. 요구사항

• API 로깅: API 엔드포인트(URI, Method) 호출 및 응답 시간(ms), 상태 코드(Status Code)를 확인할 수 있어야 합니다.
• SQL 로깅: JPA, QueryDSL을 통해 실행되는 실제 SQL문과 바인딩되는 파라미터 값을 확인할 수 있어야 합니다.
• 성능 측정: 각 SQL문의 개별 처리 시간을 측정하여 성능 병목 구간을 분석할 수 있어야 합니다.
• 로그 추적: 동시 다중 요청이 발생하는 환경에서도 특정 요청에 대한 API 로그와 SQL 로그를 명확하게 식별하고 추적할 수 있어야 합니다.
• 로그 가독성: 문제 발생 후 시간이 지난 뒤에도 로그를 쉽게 파악하고 분석할 수 있어야 합니다.

3. 구현 전략 및 선택 기술

위 요구사항을 충족시키기 위해 다음과 같은 기술과 전략을 선택했습니다.

3.1 쿼리 로깅: P6Spy

JPA가 생성하는 SQL을 상세히 로깅하기 위해 P6Spy 라이브러리를 도입했습니다.

• 선택 사유:

  • 요구 사항에 필요한 모든 기능(쿼리 파라미터, 포맷팅, 쿼리 수행 시간 측정)을 충족합니다.
  • 쿼리 포맷팅을 코드로 변경할 수 있기 때문에, 유지 보수성에 있어 뛰어나다고 판단했습니다

  기능 (Feature)	Hibernate	Log4jdbc	P6Spy
  쿼리 파라미터 실제 값 출력	X (?로 표시됨)	O	O
  SQL 포맷팅 (줄바꿈)	O	X (한 줄로 출력됨)	O (커스텀 가능)
  쿼리 수행 시간 측정	X	O	O
  쿼리 결과셋 출력	X	O	X

3.2 로그 추적: MDC (Mapped Diagnostic Context) 활용

다중 스레드 환경에서 동시 요청 시 로그가 뒤섞이는 문제를 해결하기 위해 MDC와 TraceId 개념을 도입합니다.

• MDC (Mapped Diagnostic Context) 란?
  • 로깅 프레임워크(Log4j)가 제공하는 기능으로, 각 스레드마다 고유한 메타데이터(Key-Value)를 저장할 수 있는 공간입니다. 여기에 저장된 정보는 해당 스레드에서 발생하는 모든 로그에 자동으로 포함시킬 수 있습니다.
  • 참고 자료: MDC 공식문서
• 적용 방식:
  1. 클라이언트의 HTTP 요청이 들어오는 시점(Filter의 가장 앞단)에 고유한 TraceId (예: UUID)를 생성합니다.
  2. 생성된 TraceId를 MDC에 put합니다.
  3. logback-spring.xml 등 로깅 설정 파일의 로그 패턴에 MDC의 TraceId(%X{traceId})를 추가합니다.
  4. HTTP 요청 처리가 모두 끝나는 시점에 MDC.clear()를 호출하여 스레드 풀에 반환되는 스레드의 MDC를 초기화합니다.