David Brain

App-Server-로깅-원칙

4 min read

ID: key_26_30_05_26_logging_01 Created date: 5월 30 2026 토요일

연관 문서

서버 (befw-app-server) | 서버 개발

1. 로그 레벨 정의

레벨용도출력 조건
ERROR복구 불가 예외, 외부 시스템 연결 실패, 데이터 무결성 오류항상 스택트레이스 포함
WARN예상 가능한 실패 (인증 실패, 유효성 오류, 비즈니스 규칙 위반)메시지만, 스택트레이스 제외
INFO주요 비즈니스 흐름 진입 · 완료 (API 요청/응답, 서비스 기동)운영 환경 기본 레벨
DEBUG내부 처리 단계, 조회 결과, 상태 전이개발/스테이징 환경
TRACE세부 파라미터, 쿼리 바인딩 값로컬 환경 한정

2. 로그 포맷

{timestamp} [{thread}] {LEVEL} [{requestId}] {logger} - [{layer}] {action} | {context}

예시

2026-05-30 01:09:12.976 [http-nio-8080-exec-6] INFO  [a1b2c3d4] c.t.s.b.l.c.a.AuthService - [SERVICE] LOGIN_REQUEST | email=yj.david.kim@gmail.com
2026-05-30 01:09:12.985 [http-nio-8080-exec-6] DEBUG [a1b2c3d4] c.t.s.b.l.c.a.AuthService - [SERVICE] USER_FOUND | userId=uuid-xxxx
2026-05-30 01:09:13.010 [http-nio-8080-exec-6] INFO  [a1b2c3d4] c.t.s.b.l.c.a.AuthService - [SERVICE] LOGIN_SUCCESS | email=yj.david.kim@gmail.com
2026-05-30 01:09:13.020 [http-nio-8080-exec-6] WARN  [a1b2c3d4] c.t.s.b.l.c.a.AuthService - [SERVICE] LOGIN_FAILED | reason=BadCredentials email=yj.david.kim@gmail.com

레이어 식별자

식별자위치
[FILTER]Spring Security Filter, MDC Filter
[CONTROLLER]@RestController, @RestControllerAdvice
[SERVICE]@Service (비즈니스 로직)
[ACCESS]AbstractCrudService (데이터 접근)
[MESSAGING]Solace / Kafka 수신·발행

3. MDC (Mapped Diagnostic Context) 규칙

모든 요청에 requestId (UUID 8자리) 를 MDC에 설정하여 로그 추적 가능하게 한다.

// MdcLoggingFilter에서 자동 주입
MDC.put("requestId", UUID.randomUUID().toString().substring(0, 8));

Log4j2 패턴에 %X{requestId} 포함:

%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level [%X{requestId}] %logger{40} - %msg%n

4. 필수 로그 포인트

4.1 인증/인가

포인트레벨내용
로그인 요청 수신INFOemail (비밀번호 절대 금지)
유저 조회 성공DEBUGuserId
유저 미존재WARNemail
비밀번호 불일치WARNemail
토큰 발급 성공INFOemail, expiresIn
토큰 검증 실패WARN실패 사유
인증 완료 (Filter)DEBUGemail, tenant

4.2 API 요청/응답

포인트레벨내용
API 진입INFOmethod, uri, email
API 정상 응답INFOstatus, 처리시간(ms)
비즈니스 예외WARNerrorCode, message
시스템 예외ERROR스택트레이스 포함

4.3 외부 시스템 연동

포인트레벨내용
Redis 연결 실패ERROR스택트레이스 포함
Redis 저장/조회DEBUGkey (값 제외)

5. 보안 원칙

금지 항목대안
비밀번호 (평문/해시 모두)절대 로깅 금지
Access Token 전체앞 10자리만 (token=eyJhbG...)
개인정보 전체마스킹 (yj.da***@gmail.com)

6. log4j2-spring.xml 설정 기준

<!-- 애플리케이션: DEBUG -->
<Logger name="com.tsh.starter.befw" level="DEBUG" additivity="false">
 
<!-- Auth 흐름 집중 디버깅 시: TRACE -->
<Logger name="com.tsh.starter.befw.lib.core.apService.auth" level="TRACE" additivity="false">
 
<!-- Spring Security: INFO (인증 흐름 추적 시 DEBUG로 상향) -->
<Logger name="org.springframework.security" level="INFO" additivity="false">

Graph View