공통 로깅 Aspect 설계 및 구축 - Genie-Uss/genieus GitHub Wiki

✅ 공통 로깅 Aspect 설계 및 적용

🧩 문제 상황 (Problem)

서비스가 점차 복잡해지면서 다음과 같은 관측성과 디버깅 문제에 직면했습니다:

장애 발생 시, 요청이 어느 컴포넌트까지 도달했는지 추적 불가능
Kafka 소비자나 스케줄러에서 발생하는 예외는 기존 요청 기반 로그 체계에 포함되지 않아 누락
Zipkin과 같은 분산 추적 도구는 서비스 간 흐름은 보이지만, 메서드 레벨의 진입/종료 타이밍 추적은 어려움
각 서비스마다 로깅 방식이 달라 로그 포맷과 위치가 불일치, 분석 비용 증가

🎯 선택한 해결 방안 (Decision)

Spring AOP 기반의 공통 Aspect를 정의하여, 컨트롤러·스케줄러·이벤트 리스너 등 주요 진입점에서 진입, 반환, 예외 상황을 통합적으로 로깅하는 구조를 설계했습니다.

@Aspect로 정의된 EntryExitLoggingAspect를 통해 주요 메서드 흐름을 가로채고 로그 기록
공통 설정 클래스(CommonConfig)에 LoggingConfig를 포함시켜, 모든 서비스에서 자동 적용되도록 구성
Slf4j + MDC를 활용해 traceId 및 사용자 식별 정보 등 공통 컨텍스트 정보 자동 포함

🧩 시퀀스 다이어그램 (Mermaid)

sequenceDiagram
    participant Client
    participant Controller
    participant EntryExitLoggingAspect
    participant Service

    Client->>Controller: HTTP 요청
    activate Controller
    Controller->>EntryExitLoggingAspect: 메서드 호출 인터셉트
    activate EntryExitLoggingAspect
    EntryExitLoggingAspect->>EntryExitLoggingAspect: 진입 로그 기록
    EntryExitLoggingAspect->>Service: 비즈니스 로직 호출
    activate Service
    Service-->>EntryExitLoggingAspect: 결과 반환
    deactivate Service
    EntryExitLoggingAspect->>EntryExitLoggingAspect: 반환/예외 로그 기록
    EntryExitLoggingAspect-->>Controller: 원래 결과 반환
    deactivate EntryExitLoggingAspect
    Controller-->>Client: HTTP 응답
    deactivate Controller

✅ 적용 효과 (Outcome)

컨트롤러, Kafka 리스너, 스케줄러 등 다양한 진입점에 대해 일관된 로그 출력 포맷 확보
MDC 기반의 traceId 포함 로그로 Zipkin, Loki 등과 완전한 분산 추적 연계 가능
장애 발생 시 실제 어느 메서드에서 문제가 발생했는지 추적이 용이
각 서비스에서 별도 로깅 구현 없이도 자동으로 진입/반환 로그가 기록되어 코드 간결성 유지

🔭 향후 개선 방향 (Next Steps)

🔄 ThreadLocal 기반 Context 확장: 사용자 ID, 요청 ID 등 커스텀 MDC 필드 자동 설정
⚠️ Slow Method 탐지 기능: 일정 시간 이상 소요된 메서드에 대해 WARN 로그 출력
🔐 민감 정보 필터링 정책 적용: 요청 파라미터 중 일부 민감 정보 마스킹 또는 제외 처리

💬 요약

“Spring AOP 기반의 공통 Aspect를 정의함으로써, 서비스 간 일관된 진입/반환/예외 로깅 체계를 확보하였고, 이는 장애 분석, 트레이싱, 운영 관측성 측면에서 큰 개선 효과를 가져왔습니다.”