Prometheus + Grafana로 Spring Boot 모니터링 대시보드 만들기

소개

애플리케이션 성능을 실시간으로 파악하려면 메트릭 수집과 시각화가 필수다. Spring Boot는 Micrometer를 통해 다양한 메트릭을 제공하고, Prometheus는 이들을 수집한다. Grafana는 수집된 메트릭을 시각화해 운영 상태를 한눈에 보여준다. 이 글에서는 spring boot prometheus 설정부터 grafana dashboard spring boot 구성까지 단계별로 설명한다.

사전 준비

필수 요소

• Spring Boot 애플리케이션 (2.x 또는 3.x)
• Prometheus 서버 (v2.x)
• Grafana 인스턴스
• 애플리케이션 접근 가능한 네트워크

Spring Boot에서 Prometheus 메트릭 노출

Spring Boot에 Micrometer와 Prometheus 노출 엔드포인트를 추가하면 된다. Gradle 예시는 다음과 같다.

plugins {
  id 'org.springframework.boot' version '2.7.0'
  id 'io.spring.dependency-management' version '1.0.11.RELEASE'
  id 'java'
}

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-actuator'
  implementation 'io.micrometer:micrometer-registry-prometheus'
}

application.yml 설정은 다음과 같이 actuator 노출을 활성화한다.

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  endpoint:
    prometheus:
      enabled: true
  metrics:
    enable:
      all: true

애플리케이션을 실행한 뒤 /actuator/prometheus 엔드포인트가 200으로 응답하는지 확인한다.

curl http://localhost:8080/actuator/prometheus

Prometheus 설정

Prometheus는 scrape_configs에 Spring Boot 엔드포인트를 추가해야 한다. 로컬에서 실행하는 간단한 prometheus.yml 예시는 다음과 같다.

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'spring-boot'
    metrics_path: /actuator/prometheus
    static_configs:
      - targets: ['host.docker.internal:8080']

Prometheus를 재시작하고 Targets 페이지에서 spring-boot 타겟이 정상 상태인지 확인한다. 응답이 없으면 네트워크와 포트, 경로를 점검한다.

Grafana에서 데이터 소스 연결

Grafana UI에서 Prometheus를 데이터 소스로 추가한다. 기본 설정은 다음 항목을 입력하면 된다.

• Type: Prometheus
• URL: http://localhost:9090
• Access: Server

연결 확인 후 대시보드를 만든다. Grafana에서 대시보드를 직접 만들거나, 이미 만들어진 템플릿을 가져와서 수정할 수 있다.

대시보드 구성 예시

기본 패널

• 애플리케이션 요청률: rate(http_server_requests_seconds_count[1m])
• 평균 응답시간: rate(http_server_requests_seconds_sum[1m]) / rate(http_server_requests_seconds_count[1m])
• 메모리 사용량: jvm_memory_used_bytes{area="heap"}
• 스레드 수: jvm_threads_live_threads

Grafana 쿼리 예시는 다음과 같다. 쿼리를 복사해 패널에 붙여넣으면 된다.

# 요청률
rate(http_server_requests_seconds_count[1m])

# 평균 응답시간
rate(http_server_requests_seconds_sum[1m]) / rate(http_server_requests_seconds_count[1m])

# 힙 사용률
jvm_memory_used_bytes{area="heap"}

경보(Alerts) 설정

중요 메트릭에 대한 경보를 설정하면 이상 징후를 빠르게 감지할 수 있다. 예를 들어 평균 응답시간이 일정 시간 동안 임계치보다 높으면 알림을 발생시키는 규칙을 만든다. Grafana Alerting 또는 Prometheus Alertmanager를 사용해 알림을 전송할 수 있다.

운영 팁 및 고려사항

• 메트릭 수집 주기는 운영 환경에 맞게 조정한다. 과도한 scrape는 오버헤드를 유발한다.
• 라벨(cardinality)은 낮게 유지한다. 높은 라벨 카디널리티는 Prometheus 성능 저하를 초래한다.
• 메트릭 네이밍 규칙을 일관되게 적용하면 쿼리 작성이 쉬워진다.
• 다중 인스턴스 환경에서는 서비스 디스커버리 설정을 활용한다.

문제 해결 체크리스트

• actuator 엔드포인트가 노출되어 있는지 확인
• Prometheus scrape target이 UP인지 확인
• Grafana에서 올바른 Prometheus URL을 사용 중인지 확인
• 쿼리에서 사용하는 메트릭 이름이 애플리케이션에서 실제로 존재하는지 확인

요약

이 글에서는 spring boot prometheus 설정부터 grafana dashboard spring boot 구성까지 기본 과정을 다뤘다. 핵심은 애플리케이션에서 신뢰할 수 있는 메트릭을 노출하고 Prometheus가 이를 안정적으로 스크랩하며 Grafana에서 목적에 맞게 시각화하는 것이다. 처음 구성할 때는 소규모로 시작해 모니터링 범위를 점진적으로 확장하는 것을 권장한다.