로깅 전략 가이드라인 수립에 대한 논의

[Jin409]

안녕 여러분!

이번 3차 데모데이를 준비하며 로깅의 필요성을 뼈저리게 느꼈어요. 그래서 점차적으로 로깅을 고도화하는 데에 참고할 수 있는 가이드라인이 존재한다면 어떨까 하는 생각이 들어, 로깅의 전략과 방법에 대해 고민해보고 정리해봤어요.

나름 로깅의 목적 및 dev / prod 용 서버의 특성에 대해 고려해 정리해보았는데, 참고해 의견 주세요! 🦦

같이 가이드라인을 만들어 나가 봅시다! 의문점, 질문, 토의 모두 환영입니다!

---

📄 API 응답 속도 로깅 전략

📌 1. 왜 로깅하는가?

• 병목이 발생하는 API 경로와 호출 패턴을 식별하기 위해
• 성능 저하의 원인(API, DB, 외부 I/O 등)을 분리 분석하기 위함

🗂️ 2. 어디에 출력 및 저장하는가?

• 콘솔에는 출력하지 않음 (콘솔보다는 알림으로 파악하면 충분!)
• 파일에 저장 (/logs/performance.log 등 별도 파일 분리)

🧹 3. 로그 파일은 어떻게 관리하는가?

• 용량 기준 롤링 설정
  • 10MB 초과 시 새 파일 생성
• 보존 정책
  • 최근 7일(병목 API 를 확인하고 대응하는 기간 수립 이후 조정)

🧱 4. 어떤 정보가 포함되는가?

• ✅ 요소 구성:
  • HTTP Method
  • Endpoint URI
  • 응답 시간 (ms)
  • traceId (요청 추적용)
  • status code (선택)

{
  "method": "GET",
  "uri": "/api/v1/cups",
  "durationMs": 247,
  "traceId": "9a2c134..."
}

📊 5. 시각화는 어떻게 하는가?

• 로그 수집 → CloudWatch Logs → Metric Filter

• 특정 조건 설정:

  • durationMs > 1000인 항목만 지표화
  • 일정 횟수 이상이면 Alarm 트리거
    -> 너무 알림이 많으면 이 또한 피로감으로 인해 주목하지 않게 될 것을 우려
    -> 특정 경로에서 + 특정 시간만큼 걸리고 + 일정 횟수이상이라면 트리거되도록 수정
    ex) 일회성 데이터베이스 커넥션 지연이라면?

🚨 6. 문제가 발생했을 때 대응 방식은?

• CloudWatch Alarm → SNS → Slack 연동
• 슬랙 메시지 예시:

🚨 API 응답 지연 발생
- Endpoint: /api/v1/cups
- 평균 응답 시간: 1830ms (임계값: 1000ms)
- 발생 횟수: 5회/5분

⚙️ 7. 운영 환경에 따라 다르게 구성하는가?

항목	dev 환경	prod 환경
로그 레벨	DEBUG	INFO 이상
저장 위치	콘솔	전용 파일 (콘솔 X)
시각화	없음	필수 (CloudWatch 필터 적용)
알람 연계	없음	Slack 연동 필수

추후 prod 환경이 추가되면 설정을 일부 분리

---

📄 외부 API 응답 속도 로깅 전략

📌 1. 왜 로깅하는가?

• 응답 속도가 너무 늦는다면 -> 다른 API 로 대체 여지 고려 가능
• 제어할 수 없는 외부 API 의 특성 상, 민감하게 대응 필요

🗂️ 2. 어디에 출력 및 저장하는가?

• 콘솔 출력
• 파일 저장

🧹 3. 로그 파일은 어떻게 관리하는가?

• 용량 기준 롤링 설정
  • 10MB 초과 시 새 파일 생성
• 보존 정책
  • 최근 7일(병목 API 를 확인하고 대응하는 기간 수립 이후 조정)

🧱 4. 어떤 정보가 포함되는가?

• ✅ 요소 구성:
  • 외부 API 호출 스펙
    • METHOD
    • URI
  • traceId (내부에서의 요청 식별 및 트래킹 위함)
  • 응답 시간 (ms)
  • 실제 보낸 요청
  • 실제 받은 응답

{
  "method": "GET",
  "uri": "https://api.kakao.com/v2/user/me",
  "traceId": "a7b98cfe-135d-49a1-afe2-9d90c712cc18",
  "durationMs": 183,
  "statusCode": 200,
  "requestBody": null,
  "responseBody": {
    "id": 293848291,
    "connected_at": "2025-08-07T13:15:02Z"
  }
}

📊 5. 시각화는 어떻게 하는가?

• 로그 수집 → CloudWatch Logs → Metric Filter

• 특정 조건 설정:

  • durationMs > 3000인 항목만 지표화
  • 일정 횟수 이상이면 Alarm 트리거
    • 앞선 단순 API 응답 지연보다 더 민감하게 잡을 필요성 있음

🚨 6. 문제가 발생했을 때 대응 방식은?

• CloudWatch Alarm → SNS → Slack 연동
• 슬랙 메시지 예시:

🚨 {외부 API 이름} API 응답 지연 발생
- Endpoint: /openweather/v2 ..
- 평균 응답 시간: 1830ms (임계값: 1000ms)
- 발생 횟수: 5회/5분

해당 메시지 �송신 시, 24시간 내로 담당자가 확인 및 대응

⚙️ 7. 운영 환경에 따라 다르게 구성하는가?

항목	dev 환경	prod 환경
로그 레벨	DEBUG	INFO
저장 위치	콘솔	전용 파일 (민감 정보 있을 수 있기에 콘솔 X)
시각화	없음	필수 (CloudWatch 필터 적용)
알람 연계	없음	Slack 연동 필수
마스킹 여부	회원 관련 정보 존재하는 경우	필수

---

📄 요청 로깅 전략

📌 1. 왜 로깅하는가?

• �클라이언트와의 원활한 소통 및 대응을 위해
• 추후 에러 시나리오대로 추적하며 원인을 빠르게 파악하기 위해

🗂️ 2. 어디에 출력 및 저장하는가?

• 콘솔 출력 -> dev
• 파일 저장 -> prod (민감 정보 대응 필요)

🧹 3. 로그 파일은 어떻게 관리하는가?

• 용량 기준 롤링 설정
  • 매일매일 새로운 파일로 분리
• 보존 정책
  • 1년간? (기획적으로 사용할 여지가 있지 않을까)

🧱 4. 어떤 정보가 포함되는가?

• ✅ 요소 구성:
  • HTTP Method
  • Endpoint URI
  • 응답 시간 (ms)
  • traceId (요청 추적용)
  • status code (선택)

{
  "method": "�POST",
  "uri": "/api/v1/members/me",
  "traceId": "c7836b72-2a57-41c9-9ac0-5c1551f6a2f4",
  "durationMs": 142,
  "statusCode": 200,
  "requestBody": {
    "id": 17,
    "nickname": "hero",
    "email": "hero@gmail.com"
  }
}

📊 5. 시각화는 어떻게 하는가?

• 딱히 필요 없지 않을까?

🚨 6. 문제가 발생했을 때 대응 방식은?

• 문제가 발생할 여지가 있을까? 단순 요청를 로깅하는 구성인데!

⚙️ 7. 운영 환경에 따라 다르게 구성하는가?

항목	dev 환경	prod 환경
로그 레벨	DEBUG	INFO 이상
저장 위치	콘솔	전용 파일 (민감 정보 있을 수 있기에 콘솔 X)
시각화	없음	없음
마스킹 여부	개인정보에 대해서는 필수	필수
개인 정보 노출에 대해 민감하고, 정말 '필요한' 정보에 대한 로그만 찍어야 하는 prod 환경에서는 request body 생략

**📄 에러 발생 시 로깅 전략

📌 1. 왜 로깅하는가?

• �500 에러가 발생하는 경우 -> 미처 대응하지 못하고 있는 에러들
• 각종 에러가 발생하나, 현재는 콘솔에 찍히지 않아 대응이 원활히 되지 않음

🗂️ 2. 어디에 출력 및 저장하는가?

• 콘솔 출력
• 파일 저장

🧹 3. 로그 파일은 어떻게 관리하는가?

• 용량 기준 롤링 설정
  • 매일매일 새로운 파일로 분리
• 보존 정책
  • 최근 30일 (누적된 예외 상황이 발생할 가능성이 있지 않을까)

🧱 4. 어떤 정보가 포함되는가?

• ✅ 요소 구성:
  • HTTP Method
  • Endpoint URI
  • traceId (추적용)
  • errorCode
  • status

{
  "method": "�POST",
  "uri": "/api/v1/members/me",
  "traceId": "c7836b72-2a57-41c9-9ac0-5c1551f6a2f4",
  "errorCode": "NOT_FOUND_MEMBER",
  "status" : "404"
}

📊 5. 시각화는 어떻게 하는가?

• 로그 수집 → CloudWatch Logs → Metric Filter

• 특정 조건 설정:

  • 일정 횟수 이상이면 Alarm 트리거

🚨 6. 문제가 발생했을 때 대응 방식은?

• 4xx 대 에러인 경우
  • 특정 경로에 예외가 하루동안 10번 이상인 경우 (작은 서비스이기에)
• 5xx 대 에러인 경우
  • 1번 발생시

⚙️ 7. 운영 환경에 따라 다르게 구성하는가?

항목	dev 환경	prod 환경
로그 레벨	ERROR	�ERROR
저장 위치	콘솔 (파일은 필요 없음. 실제 시나리오 아님)	콘솔 + 파일
시각화	없음	있음 (CloudWatch)
마스킹 여부	개인정보에 대해서는 필수	필수