# Log Level 기준

## 1. 목적

이 문서는 로그 레벨의 의미와 사용 기준을 정의한다.

이 문서의 목표는 다음과 같다.

- 같은 종류의 사건이 서비스마다 다른 레벨로 찍히는 일을 줄인다
- 운영에서 필요한 신호와 디버깅용 노이즈를 구분한다
- 로그 레벨이 알림, 검색, 장애 대응에 일관되게 쓰이게 한다
- ERROR/WARN/INFO/DEBUG/TRACE의 역할을 명확히 한다

## 2. 근거 수준

- Official: Spring Boot / Spring Framework 공식 문서에서 직접 확인되는 내용
- Official + Practice: 공식 설명 위에 일반적인 운영 관행을 결합한 내용
- Project Recommendation: 이 프로젝트 구조와 운영 방식에 맞춘 규칙

## 3. 기본 원칙

### 3.1 로그 레벨은 “중요도”와 “운영 행동 필요성”을 표현한다

Spring Boot는 기본 로그 출력에 level을 포함하고, observability를 logging, metrics, traces의 세 축으로 설명한다. 이 프로젝트에서 로그 레벨은 단순 출력 강도가 아니라 운영 의미를 표현한다.

프로젝트 규칙:

- 레벨은 “이 사건이 얼마나 심각한가”를 표현한다
- 레벨은 “운영자가 지금 당장 봐야 하는가”를 암시한다
- 디버깅 편의를 위해 레벨을 올려 쓰지 않는다

### 3.2 기본 운영 레벨은 INFO다

프로젝트 규칙:

- production 기본 로그 레벨은 INFO
- DEBUG/TRACE는 상시 기본값으로 열지 않는다
- 장애 분석이나 특정 모듈 추적이 필요할 때 범위를 좁혀 일시적으로 올린다

이 규칙은 Spring Framework가 TRACE와 DEBUG를 과도한 fire hose가 되지 않게 다뤄야 한다고 설명하는 방향과도 맞다.

### 3.3 FATAL은 사용하지 않는다

Spring Boot 공식 문서는 Logback에는 FATAL 레벨이 없고 ERROR로 매핑된다고 명시한다.

프로젝트 규칙:

- FATAL 레벨 사용 금지
- 치명적 장애도 ERROR로 기록
- “매우 치명적”이라는 구분은 레벨이 아니라 메시지, 에러 코드, 알림 정책으로 표현한다

## 4. 레벨별 기준

### 4.1 ERROR

의미

요청, 작업, 배치, 연동, 내부 처리 중 실패가 발생했고 정상 경로로 복구되지 않았음을 뜻한다.

프로젝트 규칙:

- 요청이 최종 실패한 경우
- 외부 연동 실패가 호출 결과 실패로 이어진 경우
- 비동기 작업/스케줄 작업이 실패로 종료된 경우
- 복구되지 않은 예외가 발생한 경우
- 데이터 정합성 문제, 시스템 오작동, 예상하지 못한 분기

이런 경우 ERROR

쓰지 말아야 할 경우

- 예외가 발생했지만 의도된 비즈니스 흐름인 경우
- 재시도로 정상 복구된 중간 실패
- validation 실패 같은 예상 가능한 클라이언트 오류를 서버 이상처럼 과장하는 경우

### 4.2 WARN

의미

즉시 실패는 아니지만 문제 가능성이 높거나, 운영자가 추후 확인할 가치가 있는 비정상 상황을 뜻한다.

프로젝트 규칙:

- 자동 복구되었지만 이상 징후가 있는 경우
- fallback이 실행된 경우
- 재시도 후 성공했지만 원인 추적이 필요한 경우
- 느린 외부 의존성, 느린 health indicator, 비정상 입력 패턴
- deprecation 사용, 설정 누락 대체값 적용, 비권장 경로 사용

이런 경우 WARN

Spring Boot는 느린 health indicator에 대해 기본적으로 warning 로그를 남기며, 그 임계값을 설정할 수 있다고 설명한다.

쓰지 말아야 할 경우

- 정상적인 분기
- 자주 발생하는 business rejection
- 운영상 행동이 전혀 필요 없는 정보성 사건

### 4.3 INFO

의미

서비스의 주요 정상 상태 변화와 운영상 의미 있는 사건을 뜻한다.

프로젝트 규칙:

- 애플리케이션 시작/종료
- 중요한 배치 시작/완료
- 의미 있는 상태 전이
- 주요 외부 연동 시작/완료
- 보안상 중요한 성공 이벤트
- 운영자가 흐름을 이해하는 데 필요한 핵심 사건

이런 경우 INFO

쓰지 말아야 할 경우

- 모든 요청 진입/종료를 무조건 INFO로 남기는 것
- 고빈도 내부 반복 처리
- 디버깅용 변수 dump

### 4.4 DEBUG

의미

장애 분석이나 개발 중 원인 파악에 도움이 되는 상세 내부 흐름 정보다.

Spring Framework는 TRACE가 DEBUG와 유사한 원칙을 따르며 과도한 로그가 되어선 안 된다고 설명한다. 이 원칙은 DEBUG에도 그대로 적용된다.

프로젝트 규칙:

- 주요 분기 결정 근거
- 내부 상태 변화 상세
- 외부 API 요청/응답 요약
- 매핑 결과 요약
- 재시도/백오프/fallback 판단 근거

이런 경우 DEBUG

쓰지 말아야 할 경우

- 민감정보 원문 출력
- 너무 큰 payload 전체 dump
- 운영 기본 레벨에서 계속 쌓이면 안 되는 고빈도 로그

### 4.5 TRACE

의미

매우 세밀한 흐름 추적용 로그다.

Spring Framework는 TRACE도 DEBUG처럼 다뤄야 하며 fire hose가 되어서는 안 된다고 설명한다.

프로젝트 규칙:

- 프레임워크/바인딩/직렬화/세밀한 분기 추적
- 특정 문제 재현 시에만 필요한 상세 이벤트
- 고빈도 루프/반복 처리의 초미세 추적

쓰지 말아야 할 경우

- production 상시 활성화
- 요청 본문, 응답 본문, 대용량 객체 전체 출력
- 민감정보 포함 가능성이 있는 상세 dump

## 5. 상황별 권장 기준

### 5.1 요청 처리

프로젝트 규칙:

- 정상 요청 전체를 기본적으로 INFO로 남기지 않는다
- 요청 실패는 최종 실패 시 ERROR
- 비정상 입력 패턴을 별도 관찰할 필요가 있으면 WARN
- 상세 요청 흐름은 DEBUG 이하

### 5.2 외부 API 연동

프로젝트 규칙:

- 최종 실패: ERROR
- 재시도 후 성공: 기본 WARN
- fallback 성공: 기본 WARN
- 단일 시도 상세 요청/응답 요약: DEBUG
- payload 전문 출력: 기본 금지, 정말 필요하면 TRACE에서도 마스킹 필수

### 5.3 비즈니스 거절

프로젝트 규칙:

- 예상 가능한 비즈니스 거절은 기본적으로 INFO 또는 무로그
- 같은 거절이 이상 징후를 뜻하면 WARN
- 정상 정책 집행을 ERROR로 기록하지 않는다

예:

- 중복 가입 시도
- 권한 없음
- 유효성 검사 실패

이런 것은 기본적으로 서버 장애가 아니다

### 5.4 예외

프로젝트 규칙:

- 요청/작업을 실패시키는 예외: ERROR
- 재시도/대체 경로로 복구된 예외: WARN 또는 DEBUG
- controller advice에서 이미 최종 실패를 기록했다면 하위 계층 중복 ERROR 로그를 피한다

## 6. 중복 로그 방지 규칙

### 6.1 같은 실패를 여러 레이어에서 모두 ERROR로 찍지 않는다

프로젝트 규칙:

- 한 실패에 대해 대표 ERROR 로그 한 번을 원칙으로 한다
- 하위 계층은 필요하면 DEBUG/WARN으로 맥락만 남긴다
- controller, service, client, advice가 같은 예외를 모두 stack trace와 함께 ERROR로 찍지 않는다

### 6.2 로깅 위치는 책임과 함께 정한다

프로젝트 규칙:

- 최종 실패 책임을 가진 경계에서 대표 로그를 남긴다
- 외부 연동 세부 맥락은 client/adapter에서 DEBUG/WARN
- 공통 예외 응답 생성은 advice가 하더라도, 실제 대표 에러 로그 위치는 프로젝트 단위로 일관되게 정한다

## 7. 민감정보와 레벨의 관계

### 7.1 레벨이 낮다고 민감정보를 찍어도 되는 것은 아니다

프로젝트 규칙:

- DEBUG/TRACE라도 비밀번호, 토큰, 주민번호, 카드번호, 이메일 전체값 등 민감정보 원문 출력 금지
- 낮은 레벨은 더 상세할 수 있을 뿐, 보안 예외 구간이 아니다
- 상세 추적이 필요하면 마스킹/요약/해시 처리한다

## 8. Correlation / Trace와의 관계

Spring Boot는 tracing이 활성화되면 로그에 correlation ID를 포함할 수 있다고 설명한다.

프로젝트 규칙:

- 레벨과 무관하게 운영 로그는 trace/correlation 연결이 가능해야 한다
- 같은 오류가 여러 로그로 흩어져도 추적 가능한 키가 있어야 한다
- traceId, principal, request path 기록 규칙은 별도 문서에서 구체화한다

## 9. 운영 설정 규칙

### 9.1 production 기본값

프로젝트 권장 기본값:

- root: INFO
- 애플리케이션 주요 패키지: INFO
- noisy framework package: 필요 시 WARN
- 특정 문제 조사 시 모듈 단위로만 DEBUG/TRACE 상향

### 9.2 일시적 상향은 범위를 좁힌다

프로젝트 규칙:

- root를 DEBUG/TRACE로 올리는 것을 기본 금지
- 특정 패키지, 특정 client, 특정 기능 단위로만 조정
- 문제 해결 후 원래 레벨로 되돌린다

## 10. 금지 규칙

다음은 기본 금지다.

- FATAL 사용
- 정상 흐름을 ERROR/WARN으로 과장
- 실패 하나를 여러 레이어에서 중복 ERROR 출력
- production 기본 레벨을 DEBUG/TRACE로 설정
- DEBUG/TRACE에서 민감정보 원문 출력
- 모든 요청/응답을 INFO로 남기는 것
- 디버깅 편의 때문에 레벨 의미를 무너뜨리는 것

## 11. 체크리스트

다음 질문에 “예”로 답할 수 있어야 한다.

- 이 로그는 해당 레벨의 운영 의미와 맞는가?
- 정상 흐름을 불필요하게 경고/오류로 올리지 않았는가?
- 같은 실패를 대표 로그 한 번으로 정리하고 있는가?
- DEBUG/TRACE가 상시 fire hose가 되지 않는가?
- 민감정보가 레벨과 무관하게 보호되는가?
- tracing/correlation과 연결 가능한가?