[Spring Boot] Docker로 3분 만에 모니터링 구축하기 (Prometheus + Grafana)

지난 포스팅에서 Spring Actuator를 통해 서버의 상태를 JSON으로 확인했습니다.

하지만 실무에서 누가 검은 화면의 글씨를 읽고 있을까요?

오늘은 Actuator(데이터 제공) + Prometheus(데이터 수집) + Grafana(데이터 시각화) 3대장을 연결하여,

멋진 그래프로 서버를 모니터링하는 방법을 구축해 봅니다.

---

1. 큰 그림 이해하기 (Architecture)

우리가 구축할 시스템은 3대장이 협력하는 구조입니다.

1. Spring Boot (Actuator): "내 현재 상태(CPU, 메모리 등)를 알려줄게!" (데이터 생성)
2. Prometheus (프로메테우스): 주기적으로 Spring Boot에 접속해서 데이터를 긁어갑니다. (데이터 수집/저장)
3. Grafana (그라파나): 수집된 데이터를 예쁜 그래프로 그려줍니다. (데이터 시각화)

---

Step 1. Spring Boot 설정 (Micrometer)

Spring Boot Actuator가 기본적으로 내뱉는 데이터(JSON)는 Prometheus가 읽을 수 없는 형식입니다.
중간에서 통역사 역할을 하는 Micrometer 라이브러리를 추가해야 합니다.

 

1. 의존성 추가 (build.gradle)

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-actuator'
    // ★ 추가: Actuator 데이터를 Prometheus가 이해하는 포맷으로 변환
    implementation 'io.micrometer:micrometer-registry-prometheus' 
}

 

2. 설정 확인 (application.yml)

management:
  endpoints:
    web:
      exposure:
        include: "*" # prometheus 엔드포인트도 노출시켜야 함

 

3. 확인
서버를 실행하고 http://localhost:8080/actuator/prometheus 에 접속해 보세요.
JSON이 아니라, 아래처럼 텍스트 형태의 데이터가 나오면 성공입니다!

# HELP jvm_memory_used_bytes The amount of used memory
# TYPE jvm_memory_used_bytes gauge
jvm_memory_used_bytes{area="heap",id="G1 Survivor Space",} 1000.0
...

---

Step 2. Prometheus & Grafana 설치 (Docker)

이 두 프로그램을 윈도우에 직접 설치하는 건 매우 번거롭습니다. Docker를 사용하면 1분 만에 띄울 수 있습니다.

바탕화면이나 편한 곳에 폴더(예: monitoring)를 하나 만들고, 그 안에 파일 2개를 만들어주세요.

 

사전준비 사항

미리 Docker를 설치해 주세요!

1) prometheus.yml (설정 파일)

Prometheus에게 "데이터를 어디서 가져올지" 알려주는 파일입니다.

global:
  scrape_interval: 5s # 5초마다 데이터 수집 (실무에선 보통 15s~1m)

scrape_configs:
  - job_name: 'spring-boot'
    metrics_path: '/actuator/prometheus' # 스프링 부트 데이터 경로
    static_configs:
      # ★ 핵심: Docker 내부에서 내 PC(로컬호스트)를 찾으려면
      # 'localhost' 대신 'host.docker.internal'을 써야 합니다!
      - targets: ['host.docker.internal:8080'] 

2) docker-compose.yml (실행 파일)

명령어 한 줄로 Prometheus와 Grafana를 동시에 실행시키는 파일입니다.

version: '3'
services:
  # 1. 프로메테우스 (데이터 수집)
  prometheus:
    image: prom/prometheus
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml # 위에서 만든 설정 파일 연결

  # 2. 그라파나 (시각화 도구)
  grafana:
    image: grafana/grafana
    container_name: grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin # 초기 비밀번호 설정

3) 실행

폴더 위치에서 터미널(CMD)을 열고 아래 명령어를 입력합니다.

docker-compose up -d

(처음엔 이미지를 다운로드하느라 시간이 조금 걸립니다.)

---

Step 3. Grafana 대시보드 만들기 (마법의 숫자 4701) 🪄

이제 화면을 띄워봅시다!

1. Grafana 접속: http://localhost:3000
2. 로그인: admin / admin (비밀번호 변경 창이 뜨면 변경하거나 Skip)
3. 데이터 소스 연결:
   • 왼쪽 메뉴 Connections -> Data Sources -> Add data source 클릭.
   • Prometheus 선택.
   • URL에 http://prometheus:9090 입력.
   • (주의: Docker 컨테이너끼리 통신하므로 localhost가 아닌 컨테이너 이름 prometheus를 씁니다.)
   • 하단 Save & Test 클릭 -> 초록색 성공 메시지 확인! ✅
     

     

4. 대시보드 가져오기 (Import) ★
   • 그래프를 일일이 그릴 필요가 없습니다. 전 세계 개발자들이 이미 만들어 둔 것을 가져오면 됩니다.
   • 왼쪽 메뉴 Dashboard -> Create Dashboard-> 우측 상단 New -> Import
   • Find and import dashboards for common applications at grafana.com/dashboards 칸에 숫자 4701 입력 후 Load.
     
     

     

   • (4701은 'JVM (Micrometer)'라는 아주 유명한 Spring Boot 전용 대시보드 ID입니다.)
   • 아래쪽 Prometheus 선택 박스에서 방금 등록한 데이터 소스 선택 -> Import 클릭.

 

---

🎉 결과 확인 (NASA 상황실 등판)

짜잔! 🎉
모니터에 뭔가 복잡하고 멋진 그래프들이 춤을 추기 시작합니다.

---

💡 마무리

이제 여러분은 단순히 "서버 켰어요"가 아니라, "서버의 힙 메모리 추이와 GC 빈도를 시각화하여 모니터링 환경을 구축했습니다"라고 말할 수 있는 개발자가 되었습니다.

Actuator와 Prometheus, Grafana의 조합은 실무(MSA 환경)에서도 거의 표준처럼 쓰이는 기술이니 꼭 한 번 실습해 보시길 바랍니다!