2.3 KiB
2.3 KiB
로깅 규칙 원칙
작성일: 2025-12-06 목적: 로그 일관성 유지, 디버깅 효율성 향상
로그 레벨 사용 규칙
| 레벨 | 사용 시점 | 예시 |
|---|---|---|
DEBUG |
상세 디버깅 정보 | 변수 값, 함수 진입/종료 |
INFO |
정상 동작 정보 | 요청 처리, 상태 변경 |
WARNING |
예상 가능한 문제 | 재시도, 폴백 처리 |
ERROR |
처리 실패 | 예외 발생, API 오류 |
CRITICAL |
시스템 중단 | DB 연결 실패, 서비스 다운 |
참고: rb8001/app/core/logger.py
장애 분석 원칙 (필수)
- 상태코드 왜곡 금지: 인증/입력/권한 오류를 500으로 재매핑하지 않는다.
- 근본 원인 우선: 임시 예외 폴백으로 증상을 숨기지 말고, 재현 가능한 원인(원문 body, 헤더, 설정, 데이터)을 직접 수정한다.
- 로그 증거 필수: 원인 판단은 같은 시각의 ingress/nginx, gateway, 서비스 로그를 함께 대조해 확정한다.
로그 포맷
구조화된 로그
logger.info(f"User {user_id} authenticated", extra={
"user_id": user_id,
"action": "authenticate"
})
JSON 로깅
- 형식: JSON (python-json-logger 사용)
- 필드:
time,level,module,msg
참고: rb8001/app/core/logger.py
로그 위치 원칙
- 컨테이너 내부: 서비스별 로그 파일 분리
- 호스트 백업: 정기적 백업 (일별 스케줄)
- 실제 경로는 각 서비스 README 참조
참고: AGENTS.md:133-137
로그 확인 원칙
- 실시간 로그: Docker 로그 명령어 사용
- 파일 로그: 로그 파일 직접 확인
- 에러 필터링: grep으로 에러/경고 필터링
참고: AGENTS.md:133-137
로그 보관 원칙
- Docker JSON 로그: 컨테이너별 자동 생성
- 중앙 집중 로그: OpenSearch 등 외부 시스템 활용
- 실제 주소/인덱스는 각 서비스 README 참조
참고: AGENTS.md:137-142
로깅 모범 사례
DO
- 요청/응답 로깅 (INFO)
- 에러 상세 정보 포함 (ERROR)
- 사용자 ID 포함 (개인정보 제외)
DON'T
- 민감 정보 로깅 (비밀번호, 토큰)
- 과도한 DEBUG 로그 (프로덕션)
- 중복 로그 (같은 정보 반복)
업데이트: 로깅 규칙 변경 시 즉시 반영