[찐빵] 옵저버빌리티 설계

찐빵 서비스의 경우 MySQL, MongoDB, Redis, S3, Google Sheets 등 다양한 외부 리소스와 상호작용하고, 건물·리뷰 조회/관리, 지도 검색, 사용자 인증·설정 등의 다양한 API들도 존재하기에 메트릭과 구조적인 로그 체계가 필수적이므로 옵저빌리티를 설계해보았습니다..!

 

1. 수집할 핵심 메트릭 정의(API latency, error rate, RPS 등)

범주 메트릭 태그/분류 설명 및 수집 이유

HTTP 요청 지연	http.server.requests (Timer)	uri, method, status, outcome, exception	모든 REST 엔드포인트(건물 상세, 리뷰 CRUD, 지도 검색, 인증/사용자 API)의 응답 시간을 계층별로 가시화하여 병목 식별 (p50/p95/p99 추출)
HTTP 오류율	http.server.requests (Counter)	동일 + status 그룹 (2xx/4xx/5xx)	status >= 400 비율을 계산해 API 안정성 모니터링. ControllerAdvice가 공통 예외를 처리하므로 특정 예외 유형을 태그로 전파하면 오류 유형별 추적이 가능할듯
요청 처리량(RPS)	http.server.requests.count	uri, method	주요 API(지도 검색/리뷰/건물)의 초당 요청 수를 측정해 갑작스런 트래픽 급증을 감지
DB 커넥션 풀 상태	hikaricp.connections.*	pool	MySQL 기반 리뷰/지도 조회가 집중되므로 Hikari 커넥션 사용량·대기시간을 관찰해 풀 사이즈를 조정
Mongo/Redis 연산률	mongodb.command.*, redis.commands	collection, command, result	리뷰 상세·키워드(Mongo), 메일/토큰 캐시(Redis)의 호출량·실패율 추적
외부 연동 지연	사용자 정의 Timer (S3, Google Sheets, 메일, OAuth)	service, operation, status	S3 업로드/삭제, Google Sheets append, 메일 전송, OAuth 토큰 재발급 등 외부 I/O의 평균 지연과 실패율을 별도 측정
스케줄러 성과	Timer/Counter(user.scheduler.finalizeDeletionBatch)	result	탈퇴 유예 만료 사용자 정리 배치의 실행 주기·성공/실패 횟수를 수집

2. 커스텀 메트릭 대상(중요 비즈니스 로직) 식별

• 리뷰 작성/수정/삭제 성공·실패 카운터 및 처리 시간
  • 리뷰 CRUD는 저장소(JPA, Mongo, S3)를 갱신하므로 타입(일반/기숙사/공인중개사)별로 Counter와 Timer를 두어 실패 원인을 분류
• 지도 검색/마커 조회 성공률 및 결과 개수 히스토그램
  • 지도는 필터와 연산을 수행하므로 응답 시간과 반환 개수를 측정해 필터 조합에 따른 부하를 분석
• 건물 상세 요청 수와 기숙사 분기 비율
  • 기획용. 사용자들의 관심은 원룸과 같은 건물일지 기숙사인지 파악하기 위함
  • 상세 응답은 건물 타입별로 키워드 집계를 사용하므로 사용자 관심 분포를 파악 ⇒ 차후 캐싱에도 도움될 듯..?
• OAuth 로그인/회원가입/토큰 재발급 성공·예외 카운터
  • 소셜 로그인 흐름에서 예외(탈퇴 사용자, 토큰 만료)를 세분화해 인증 이슈를 추적
• 메일 인증 코드 발송·검증 시도 및 실패 사유별 Counter
  • 허용 도메인 검증, 코드 미존재, 만료 등의 실패 유형을 분리해 사용자 경험을 개선
• 북마크/최근 본 리뷰 API 호출 수와 예외율
  • A/B 테스트. 향후 탭 삭제를 해도 될까에 대해 여부 판단
  • 사용자 개인화 기능의 사용량을 측정해 UI 개선 우선순위를 판단
• Google Sheets 전송 성공률
  • 사용자 탈퇴 사유·문의 전송 시 Sheets API 오류를 추적
• S3 presigned URL 발급/삭제 오류 카운터
  • 파일 업로드용 URL 발급과 삭제 오류를 추적해 CDN 연계 이상을 조기에 발견
• 탈퇴 배치 처리 건수
  • UserScheduler에서 삭제된 계정 수를 Counter로 기록해 데이터 정리 현황을 모니터링

3. JSON 구조화 로그 필드 목록 정의(TraceID, URI, Status 등)

traceId의 경우 MDC가 필요해서 향후 도입할 수도 있습니다. 감안해서 봐주셔욥

필드 내용 이유

timestamp, level, logger, thread	기본 메타데이터	시계열 정렬 및 로거 식별을 위해 필요
traceId, spanId, requestId	요청 상관관계	분산 추적·멀티 서비스 연동 시 연관 로그 추적
service, environment, version	배포 메타	다중 환경/버전 운영 시 필터링
httpMethod, uri, query, status, latencyMs	HTTP 컨텍스트	주요 API 호출 정보를 구조화하여 SLA 위반 원인 파악
remoteIp, userAgent, referer	클라이언트 정보	비정상 패턴(봇/공격) 탐지
userId, oauthProvider	인증 컨텍스트	@AuthenticationPrincipal Users를 통해 확보한 식별자 기록
responseCode, errorCode, exception, stacktrace	오류 정보	ControllerAdvice에서 예외 유형과 메시지를 JSON 필드로 출력하여 분석 자동화
businessEvent, entityId, resultCount	도메인 키	예: review.create, map.search 등 비즈니스 이벤트 구분 및 결과 크기 기록

4. Actuator 노출 endpoint 범위 확정

현재는 health, info만 외부 노출되어 있음

• Production [Release 브랜치]
  • health, info, metrics, prometheus endPoint
  • /prometheus는 VPC 내부 혹은 Sidecar 프록시를 통해서만 접근; Spring Security 또는 API Gateway로 보호 (민감 정보가 많아 그라파나 클라우드로만 나갈 수 있도록)
  • health는 liveness/readiness 분리(management.endpoint.health.probes.enabled=true) 후 외부 로드밸런서에는 간략 응답만 전달
• Dev/Staging [Test 브랜치]
  • 디버깅 목적의 /loggers, /env, /configprops 등을 추가 노출하되, Basic Auth 또는 IP ACL로 제한
  • show-details=always로 health 세부 정보를 개발자에게 제공

5. Micrometer 바인더 리스트 확정(JVM/Thread/GC/DB/Redis 등)

바인더 적용 이유

JvmMemoryMetrics, JvmGcMetrics, JvmThreadMetrics, ClassLoaderMetrics, ProcessorMetrics, UptimeMetrics	Spring Boot JVM 애플리케이션 기본 리소스 감시
LogbackMetrics	SLF4J/Logback 로거를 사용하므로 로그 이벤트를 카운트하여 경고/오류 폭주 감지
TomcatMetrics	내장 컨테이너 스레드/커넥션 상태 파악
HikariDataSourceMetrics, HibernateMetrics	JPA & Hikari 기반 DB 접근의 커넥션 풀, 쿼리 캐시 상태 추적
MongoMetricsCommandListener	리뷰 상세·키워드 컬렉션 MongoDB 사용에 대한 지표 수집
LettuceMetrics (또는 RedisConnectionMetrics)	RedisTemplate/StringRedisTemplate 기반 인증 코드/토큰 저장소 성능 모니터링
ExecutorServiceMetrics / SchedulerMetrics	@Scheduled 삭제 배치 등 스케줄러 스레드풀 상태 추적
사용자 정의 MeterBinder (S3, Mail, Google API)	외부 API 클라이언트(S3, Google Sheets, MailSendService) 호출의 지연/오류를 묶어 보고

6. 메트릭·로그 정책 문서화(dev/prod)

공통 정책

• 메트릭/로그 Naming 규칙, 태그 사용 가이드, PII(개인정보) 마스킹 규칙 문서화
• 배포 시점마다 버전 태그(buildVersion)를 메트릭과 로그에 포함

Development

• 샘플링 비율을 높여(예: 100%) 상세 로그 및 디버깅용 메트릭 수집
• Actuator에서 추가 엔드포인트(loggers, env) 허용, 콘솔 Pretty JSON 로그 사용
• 메트릭 저장은 경량 Prometheus/InfluxDB 등 로컬 인스턴스를 사용하고, 7일 보관

Production

• 로그 샘플링/레벨 정책: INFO 기본, ERROR는 전량 수집, DEBUG는 비활성
• JSON 로그를 중앙 수집(ELK, Cloud Logging) 후 30일/90일 보관 정책
• 메트릭은 Prometheus→Grafana 대시보드, 혹은 Cloud Monitoring에 연동; 30~90일 유지
• PII가 포함될 수 있는 필드는 해시 처리 후 저장, 요청/응답 Body는 비활성(필요 시 화이트리스트만)
• 비상 상황을 대비해 Rate Limit·Circuit Breaker 메트릭을 추가 문서화

⇒ 문서화에 대해서는 AI한테 맡겨봤는데 위에 적힌 내용은 30, 90일이지만, 그라파나 클라우드 Free Tier의 경우에는 14일 밖에 저장이 안된다는 슬픈 사실…