프로젝트에서 애플리케이션 메트릭을 Prometheus로 수집하기 위해 Spring Boot에 Prometheus를 연동했습니다. 이 글에서는 제가 마주했던 문제와 그 원인, 그리고 어떻게 해결했는지를 기록합니다.
시작: Spring Boot Actuator만으로는 충분할까?
보통 Prometheus와 Spring Boot를 연동할 때는 다음 의존성을 추가합니다:
implementation 'org.springframework.boot:spring-boot-starter-actuator'
그리고 application.yml에 아래와 같이 설정하면 /actuator/metrics 등의 엔드포인트가 활성화됩니다:
management:
endpoints:
web:
exposure:
include: health,info,metrics,prometheus
metrics:
export:
prometheus:
enabled: true💡 참고로 include: "*"로 모든 엔드포인트를 노출할 수도 있지만, 운영 환경을 고려해 필요한 항목만 명시적으로 포함했습니다. actuator는 편리하지만 보안 리스크가 있어, 전체 노출보다는 필요한 항목만 선택적으로 관리하는 것이 더 안전한 운영 방식이라 판단했습니다.
이후 Prometheus 서버가 http://localhost:8080/actuator/prometheus를 스크랩하도록 설정하면 된다고 생각했습니다.
그런데 문제는 여기서부터였습니다.
❌ 예상치 못한 장애
Spring Boot 애플리케이션은 정상적으로 기동되었고 /actuator 페이지도 잘 열렸습니다. 하지만…
- http://localhost:8080/actuator/prometheus 요청 → 404 에러
- 콘솔 로그에 다음과 같은 메시지 출력:
No static resource actuator/prometheus.
처음에는 이 메시지를 보고 정적 리소스 설정 문제라고 오해했습니다. 즉 /static/actuator/prometheus 같은 파일이 없는 것처럼 보여서 의존성에 문제가 있다고 생각했습니다(추후 디버깅 삽질로 web, webflux 의존성 충돌 의심을 합니다). 단순히 정적 파일이 없다고 생각했고, actuator를 잘 몰랐으니 이 사태가 납니다.
하지만 actuator 경로는 일반적인 정적 리소스가 아닌, Spring이 노출하는 동적 엔드포인트입니다. 따라서 이 메시지는 /actuator/prometheus가 아예 등록되지 않았다는 뜻입니다.
원인 분석: Prometheus registry가 없었다
결론부터 말하자면, 아래 의존성을 추가하지 않았기 때문입니다:
implementation 'io.micrometer:micrometer-registry-prometheus'
Spring Boot는 내부적으로 Micrometer를 통해 다양한 메트릭을 수집하지만, Prometheus와의 연동은 별도의 모듈로 분리되어 있습니다. 이 모듈이 없으면 /actuator/prometheus 엔드포인트 자체가 생성되지 않습니다.
참고
💡 Spring Boot 2.0 이후부터는 Micrometer가 기본 메트릭 수집 도구로 사용되며, Prometheus export 기능은 별도 registry로 제공됩니다.
🙃 디버깅 삽질기: Web vs WebFlux 의존성 문제?
처음엔 의심을 잘못된 곳에 했습니다. spring-boot-starter-web과 webflux 의존성을 동시에 쓰고 있었고, 그게 원인일 수 있다고 생각했죠.
implementation 'org.springframework.boot:spring-boot-starter-web'
// implementation 'org.springframework.boot:spring-boot-starter-webflux'
Web과 WebFlux는 각각 DispatcherServlet과 WebHandler 기반의 서로 다른 웹 엔진을 사용하기 때문에 충돌 가능성이 있습니다. 실제로 이 둘을 함께 쓰는 건 일반적으로 권장되지 않습니다. actuator 관련 빈의 해석 순서나 우선순위가 꼬일 수 있다는 것도 문서에서 확인했습니다.
하지만 이번 이슈는 의존성 충돌 문제가 아니라, registry가 빠졌기 때문이었습니다. webflux를 제거해도 문제가 해결되진 않았습니다.
🛠 최종 해결
아래와 같이 Prometheus registry 모듈을 추가하고 애플리케이션을 재기동하자 /actuator/prometheus가 정상적으로 열렸습니다.
implementation 'io.micrometer:micrometer-registry-prometheus'
Prometheus 서버에서도 상태가 UP으로 바뀌었고, 메트릭이 수집되기 시작했습니다.
배운 점
이번 경험을 통해 Spring Boot Actuator만으로는 Prometheus 연동이 되지 않는다는 걸 체감했습니다. 또한:
- Micrometer는 유연한 메트릭 수집 시스템이지만, 타 시스템(Prometheus, Datadog 등) 연동은 별도 모듈이 필요하다
- Web과 WebFlux는 동시에 사용하지 않는 것이 좋다
단순히 작동하는 코드 이상으로, 왜 이렇게 동작하는지 이해하는 것이 중요하다는 걸 다시 느꼈습니다.