구조화된 JSON 로그: 개발자를 위한 가이드

구조화된 JSON 로깅: 개발자를 위한 실전 가이드

현대 분산 시스템에서 로깅은 관찰 가능성(observability)의 핵심 요소입니다. 메트릭이나 트레이스와 달리 로그는 애플리케이션 이벤트를 분석할 때 가장 유연합니다. 이 가이드는 구조화된 JSON 형식, MDC 컨텍스트, 명확한 에러 레벨 구분을 활용한 효과적인 로깅 구현 패턴을 구체적으로 제시합니다.

일반 텍스트 로그보다 구조화된 로그가 우월한 이유

전통적인 일반 텍스트 로그는 콘솔에서 읽기 쉽지만 자동화된 처리에서 큰 골칫거리입니다. 복잡한 정규식으로 파싱해야 하고, 특정 데이터 추출이 어렵고, 형식 변경은 악몽입니다. 분산 시스템에서 인시던트 발생 시 여러 소스에서 빠른 분석이 필요할 때 이런 문제는 치명적입니다.

구조화된 JSON 로그는 이러한 문제를 해결합니다:

• 특정 필드별 검색과 필터링 간소화
• 검색 시스템에서 부분 인덱싱 가능
• 인시던트 후 데이터 추출 자동화
• 개인정보 필터링과 메타데이터 추가 용이

비효과적인 일반 텍스트 로그 예시:

2025-03-15 10:16:01.795 INFO 12345 --- [nio-8080-exec-1] c.e.UserController : User saved to DB: User{id=123, [email protected], role=USER}

구조화된 JSON 로그 예시:

{
  "timestamp": "2025-03-22T10:15:30.123Z",
  "level": "ERROR",
  "service": "auth-service",
  "traceId": "1fd7a997-6517-4b63-9baa-4238f8012734",
  "entrypoint": "HTTP request POST /api/user/auth",
  "message": "사용자 인증 실패",
  "user_id": "user-789",
  "error": {
    "type": "InvalidCredentials",
    "details": "제공된 비밀번호가 일치하지 않습니다"
  }
}

엔드투엔드 추적을 위한 MDC(Mapped Diagnostic Context)

SLF4J의 MDC는 호출 체인을 통한 컨텍스트 정보 전달 문제를 해결합니다. 모든 메서드에 ID를 수동으로 전달하는 대신 현재 실행 스레드에 데이터를 연결합니다.

MDC 주요 사용 측면:

• 비즈니스 식별자 — user_id, order_id, transaction_id
• 기술 컨텍스트 — traceId, spanId (추적용)
• 진입점 메타데이터 — 진입점 유형, 재시도 횟수
• 자동 정리 — 요청 처리 후 항상 컨텍스트 정리

MDC는 진입점에서 빛을 발합니다. 비즈니스 ID가 처음부터 사용 가능해야 하며, 페이로드 읽기 전에 헤더에서 추출하는 경우가 많습니다.

진입점과 로깅

진입점(EP)은 비즈니스 로직 실행을 시작하는 추상화입니다. 현대 앱의 일반적인 유형:

• HTTP/REST 서버
• gRPC 서버
• Kafka 컨슈머
• 크론 잡 및 스케줄링 작업
• 메시지 큐 리스너

모든 EP는 일관된 로깅 스키마를 따라야 합니다:

• 입력 — 요청 메타데이터와 페이로드
• 실행 컨텍스트 — 비즈니스 ID, 기술 파라미터
• 출력 — 처리 결과 또는 에러
• 상태 — 성공/실패 (재시도 포함)

분산 시스템에서의 에러와 경고 구분

분산 시스템에서 재시도는 신뢰성을 위한 표준이며, 로깅 전략에 직접 영향을 줍니다:

WARN 레벨 사용:

• 중간 재시도 시 에러
• 재시도로 해결 가능한 일시적 실패
• 즉시 운영자 주의 불필요한 문제

ERROR 레벨 예약:

• 최종 실패 시도
• 추가 재시도 무의미한 치명적 에러
• 즉시 개입 필요한 상황

재시도 횟수는 높은 수부터 낮은 수로(예: 2 → 1 → 0), 0이 마지막 시도입니다. 최종 에러 필터링이 간단해집니다.

인터셉터를 활용한 실전 구현

현대 프레임워크는 횡단 관심사(cross-cutting concerns)를 위한 인터셉터를 제공합니다. 인터셉터를 통한 진입점 로깅 흐름:

• 컨텍스트 초기화 — MDC에 traceId, spanId 설정
• 진입 로그 — 메타데이터와 입력 캡처
• 요청 처리 — MDC 자동 전파와 비즈니스 로직 실행
• 종료 로그 — 결과 또는 에러 기록
• 컨텍스트 정리 — 모든 MDC 데이터 제거

주요 구현 요소:

• EP 유형별 진입/종료 로깅 인터셉터
• 추적 통합 (Jaeger, Zipkin)
• 헤더에서 비즈니스 ID 자동 추출
• 일관된 JSON 로그 직렬화

구조화된 로그의 필수 필드

일관성과 분석 용이성을 위해 모든 로그에 포함:

• 핵심 기술 필드

- ISO-8601 형식 타임스탬프

- 로그 레벨 (ERROR, WARN, INFO, DEBUG)

- 서비스 이름과 버전

- 앱 인스턴스 ID

• 실행 컨텍스트

- 요청 상관관계용 traceId와 spanId

- requestId

- 진입점 유형과 이름

- 재시도 횟수

• 비즈니스 컨텍스트

- 주요 비즈니스 ID (user_id, order_id 등)

- 요청 메타데이터 (HTTP 메서드, 엔드포인트, 컨슈머 그룹)

- 환경 (스테이지, 리전, 클러스터)

• 이벤트 데이터

- 사람이 읽기 쉬운 메시지

- 구조화된 이벤트 세부사항

- 에러 스택트레이스 (ERROR용)

- 지속 시간 (EP 로그용)

관찰 가능성 생태계와의 통합

구조화된 로그는 독립적이지 않습니다. 완전한 관찰 가능성의 일부입니다:

메트릭 상관관계:

• 로그와 메트릭 간 공유 ID
• 에러 로그를 에러율 메트릭에 연결
• 로그로 메트릭 이상 현상 컨텍스트화

추적 통합:

• 로그와 트레이스 간 통합 traceId/spanId
• 로그 세부사항으로 트레이스 보강
• 로그로 특정 스팬 디버깅

자동화 처리:

• 로그 패턴 기반 알림
• 인시던트 관리 시스템 훅
• 복구용 데이터 자동 추출

주요 요약

• JSON 구조화 로그는 자동 처리와 분석을 위한 기계 판독 형식 제공.
• MDC 컨텍스트는 메서드 시그니처 변경 없이 호출 체인에 비즈니스 ID 전파.
• 명확한 에러/WARN 구분은 재시도 로직 지원과 모니터링 노이즈 감소.
• 통합 EP 로깅 스키마는 분산 트랜잭션 분석 일관성 보장.
• 표준 필드 세트는 이벤트 상관관계와 효율적 검색 가능.

— Editorial Team