로깅(Logging)

📋 로깅(Logging) 완벽 가이드

개발할 때 꼭 알아야 할 로깅의 모든 것을 정리했습니다.

---

🤔 로깅이란?

프로그램이 실행되면서 일어나는 일들을 기록하는 것

쉽게 말해서 프로그램의 블랙박스예요.

자동차 사고 나면 블랙박스 확인하듯이, 서비스에 문제 생기면 로그를 확인합니다.

 

---

💡 왜 필요한가?

상황로깅 없을 때로깅 있을 때

에러 발생	"뭐가 문제지...?"	"아, 여기서 null이었네"
유저 문의	"재현이 안 되는데..."	"이 시점에 이런 요청을 했네"
성능 문제	"왜 느리지...?"	"이 API가 3초나 걸리네"
장애 복구	"언제부터 문제였지...?"	"14:30부터 에러 급증했네"

---

📊 로그 레벨

로그에는 심각도가 있어요. 낮은 것부터 높은 순서로:

DEBUG	개발할 때 상세 정보	"변수 x = 123"
INFO	정상 동작 기록	"서버 시작됨", "주문 완료"
WARNING	잠재적 문제, 당장은 OK	"응답 느림", "재시도 성공"
ERROR	에러 발생, 기능 실패	"결제 실패", "API 연결 실패"
CRITICAL	심각, 서비스 중단 위험	"DB 연결 끊김", "메모리 부족"

---

🌍 환경별로 다르게

환경로그 레벨이유

개발 (local)	DEBUG	다 보고 싶으니까
테스트 (staging)	INFO	적당히
운영 (production)	WARNING	중요한 것만, 용량 관리

운영에서 DEBUG 켜면 로그 파일이 폭발해요 💥

---

✅ 뭘 로깅해야 하나?

로깅해야 하는 것

상황레벨예시

서버 시작/종료	INFO	"서버 시작 - 포트: 8000"
API 요청/응답	INFO	"POST /order - 200 - 150ms"
외부 API 호출	INFO	"업비트 API 호출 성공"
중요한 비즈니스 동작	INFO	"주문 생성 - ID: 123"
예상 가능한 실패	WARNING	"재고 부족으로 주문 실패"
에러 발생	ERROR	"결제 실패 - 카드 거절"
예외 발생	ERROR	"예상치 못한 에러 + 스택트레이스"

 

❌ 로깅하면 안 되는 것 (보안!)

항목이유

비밀번호	보안
API 키 / Secret	보안
카드번호 / 계좌번호	보안
주민번호	개인정보
토큰 전체 값	보안

 

 

❌ "로그인 시도 - user: john, password: 1234"
✅ "로그인 시도 - user: john"

❌ "API 호출 - key: sk_live_abc123xyz"
✅ "API 호출 - key: sk_live_***"

---

📝 로그 포맷

기본 구조

 

[시간] [레벨] [위치] 메시지

실제 예시

 

 

2025-01-25 14:30:00 | INFO  | order.service | 주문 생성 완료 - orderId: 123
2025-01-25 14:30:01 | ERROR | payment.service | 결제 실패 - userId: 456
2025-01-25 14:30:02 | INFO  | order.service | 주문 취소 처리 - orderId: 123

포함하면 좋은 정보

timestamp	언제	2025-01-25 14:30:00
level	심각도	INFO, ERROR
location	어디서	order.service
message	무슨 일	주문 생성 완료
context	추가 정보	orderId: 123
duration	소요 시간	150ms

---

🔍 Request ID로 추적하기

하나의 요청이 여러 단계를 거칠 때, 같은 ID로 묶어서 추적해요.

 

 

[req_abc123] 14:30:00 | INFO  | API 요청 수신 - POST /order
[req_abc123] 14:30:00 | INFO  | 재고 확인 - 10개 남음
[req_abc123] 14:30:01 | INFO  | 결제 요청 시작
[req_abc123] 14:30:02 | INFO  | 결제 완료 - paymentId: 789
[req_abc123] 14:30:02 | INFO  | 주문 생성 - orderId: 123
[req_abc123] 14:30:02 | INFO  | API 응답 - 200 - 2000ms

나중에 문제 생기면 req_abc123 검색하면 전체 흐름이 보여요!

---

📁 로그 저장 위치

콘솔 (stdout)	개발 중 확인	바로 보임, 저장 안 됨
파일	서버에 저장	검색 가능, 용량 관리 필요
외부 서비스	모니터링	CloudWatch, Datadog 등

파일 저장 시 팁

 

 

logs/
├── 2025-01-23.log
├── 2025-01-24.log
└── 2025-01-25.log

→ 일별로 분리
→ 오래된 건 자동 삭제 (30일 등)

---

🔔 로그 레벨별 알림

DEBUG	✅	❌
INFO	✅	❌
WARNING	✅	선택
ERROR	✅	✅ 텔레그램/슬랙
CRITICAL	✅	✅ 즉시 알림

---

🎯 좋은 로그 vs 나쁜 로그

❌ 나쁜 로그

 

 

error occurred
failed
something went wrong

→ 뭐가 문제인지 알 수 없음

✅ 좋은 로그

결제 실패 - userId: 123, orderId: 456, reason: 카드 한도 초과
업비트 API 타임아웃 - 요청: GET /v1/ticker, 소요: 30s
주문 생성 실패 - 재고 부족, productId: 789, 요청: 5개, 재고: 2개

→ 누가, 뭘, 왜 실패했는지 명확

---

✅ 로깅 체크리스트

• 로그 레벨 구분해서 사용
• 환경별로 로그 레벨 다르게 설정
• 민감 정보 마스킹 처리
• Request ID로 요청 추적 가능
• 에러 로그에 충분한 context 포함
• 로그 파일 로테이션 설정 (일별/용량별)
• 중요 에러는 알림 연동

---

📌 한 줄 요약

 

 

로깅 = 프로그램의 블랙박스

잘 남겨두면 → 문제 생겨도 금방 해결
안 남기면 → "뭐가 문제지...?" 삽질