25.03.31 Spring Boot Acturator , Prometheus, Grafana

개요

모니터링에 대한 강의 통해 학습한 Acturator, Prometheus, Grafana에 대해 어떤 건지 제대로 알고 사용하고 싶어서 

글로 정리해 두고 복습해 본다.

 

---

 

세 가지 도구의 관계

Spring Boot Acturator , Prometheus, Grafana는 서버 및 애플리케이션 모니터링을 구축하는 핵심 기술 스택이다.

서로 협력하여 데이터 수집 -> 저장 -> 시각화의 과정을 수행할 수 있게 해 준다.

 

Spring Boot Actuator

• 애플리케이션의 상태 및 성능 지표(메트릭)를 제공하는 역할
• 예: CPU 사용량, 메모리 사용량, DB 연결 수, HTTP 요청 수 등

Prometheus

• Actuator에서 제공하는 메트릭 데이터를 주기적으로 수집하여 저장
• 시계열(time-series) 데이터베이스 역할

Grafana

• Prometheus에 저장된 데이터를 기반으로 대시보드를 구성하여 시각적으로 표현
• 경고(Alerting) 기능도 지원하여 문제 발생 시 알림 전송 가능

 

---

 

Spring Boot Actuator 이란?

Spring Boot 애플리케이션의 상태 및 성능 정보를 제공하는 라이브러리이다.

내부 동작을 쉽게 모니터링할 수 있도록 다양한 엔드 포인트를 제공한다.

 

주요 기능 

• 헬스 체크 ( Health Check ) : 애플리케이션의 상태 확인 가능 
• 메트릭 수집 ( Metrics Collection ) : CPU, 메모리 사용량, GC ( Garbage Collection ) 통계
• 트래픽 모니터링 ( HTTP 요청 수, 응답 시간 분석 )
• 로그 레벨 변경 및 뷰어 제공
• 스레드 덤프 ( Heep Dump ) 및 JVM 상태 확인

 

기본 설정 및 사용법

의존성 추가

implementation 'org.springframework.boot:spring-boot-starter-actuator'
implementation 'org.springframework.boot:spring-boot-starter-web'

 

applicaion.properties 설정

#모든 엔드포인트 노출 설정
management.endpoints.web.exposure.include=* 

#헬스 체크 엔드포인트 상세 정보 표시 설정
management.endpoint.health.show-details=always

 

모든 엔드포인트를 노출 설정하는 것은 개발 및 테스트환경에서는 유용하겠지만,

운영 환경에서는 보안 위험을 증가할 수 있다. 필요한 엔드 포인트만 노출하는 것이 권장된다.

 

기본적으로 헬스 체크 엔드포인트는 요약된 상태 정보만 제공하며, 상세 정보는 노출되지 않는다.

상세한 정보를 파악하기 위해  management.endpoint.health.show-details=always 설정을 통해
/actuator/health 엔드포인트에서 헬스 체크 정보를 항상 상세히 보여주도록 설정하는 것이다.

 

헬스 체크 엔드포인트에서 상세 정보를 항상 노출하는 설정 역시 운영 환경에서는 민감한 정보를 포함할 수 있으므로, show-details설정을 when_authorized 옵션을 사용하는 것이 좋다.

 

위의 설정은 학습할 때만 사용하는 걸 추천한다.

 

주요 Actuator 엔드포인트

엔드포인트	설명
/actuator/health	애플리케이션의 현재 상태 확인 (UP/DOWN)
/actuator/metrics	CPU, 메모리 사용량, HTTP 요청 수 등의 메트릭 제공
/actuator/env	환경 변수 및 설정 값 확인
/actuator/loggers	애플리케이션 로그 레벨 확인 및 변경
/actuator/mappings	사용 가능한 모든 API 엔드포인트 조회
/actuator/beans	스프링 컨텍스트에서 관리하는 빈 목록 확인

 

---

 

Prometheus 란?

오픈소스 시스템 모니터링 및 경고 도구이다. 

SoundCloud에서 시작되어 현재는 Cloud Native Computing Foundation(CNCF)에서 호스팅 하고 있다.

시계열 데이터(Time-Series Data)를 저장하고 쿼리 할 수 있는 모니터링 도구이며 주기적으로 데이터를 가져와 저장하고, 필요할 때 쿼리를 통해 분석할 수 있다.

 

핵심 기능

• Spring Boot Actuator에서 제공하는 메트릭을 주기적으로 수집
• HTTP 기반의 Pull 방식 ( Prometheus가 직접 데이터를 가져간다 )
• 시계열 데이터 저장 및 분석
• 알람(Alert) 기능 제공 (Prometheus AlertManager 활용 가능)
• 다양한 데이터 소스(Kubernetes, Docker, AWS 등)와 연동 가능

주요 구성 요소

 

• Prometheus 서버
  • 메트릭 데이터를 주기적으로 수집(Scrape)하여 시계열 데이터베이스(TSDB)에 저장하는 핵심 컴포넌트
• Exporters
  • 특정 애플리케이션이나 시스템의 메트릭을 Prometheus가 이해할 수 있도록 변환하는 도구
  • 예시: Node Exporter(서버 메트릭), PostgreSQL Exporter(DB 메트릭), Spring Boot Micrometer
• Pushgateway
  • 짧은 수명의 작업(Job)에서 메트릭을 푸시할 때 사용 (예: 배치 작업, 크론 작업)
• Alertmanager
  • Prometheus에서 발생한 경고(Alert)를 이메일, Slack 등으로 알림 전송
• Grafana
  • Prometheus 데이터를 시각화하는 대시보드 도구

 

기본 설정 및 사용법

의존성 추가

runtimeOnly 'io.micrometer:micrometer-registry-prometheus'
implementation 'org.springframework.boot:spring-boot-starter-actuator'
implementation 'org.springframework.boot:spring-boot-starter-web'

 

 

application.properties 수정

management.endpoint.prometheus.enabled=true

Spring Boot Actuator에서 Prometheus 엔드포인트를 활성화하는 설정이다.

Prometheus가 메트릭을 수집할 수 있도록 /actuator/prometheus 엔드포인트를 활성화하고 

Spring Boot 애플리케이션에서 Micrometer 라이브러리를 통해 Prometheus 메트릭을 제공할 수 있도록하는 설정이다

Prometheus 설정 파일 ( prometheus.yml ) 작성

Spring Boot 애플리케이션의 Actuator에서 메트릭을 가져오려면 Prometheus 설정이 필요하다.

global:
  scrape_interval: 15s

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

 

host.docekr.internal은  Docker에서 제공하는 특수한 DNS 이름으로, Docker 컨테이너가 호스트 머신(즉, Docker를 실행하는 컴퓨터)의 네트워크 서비스에 접근할 수 있도록 합니다. 이를 통해 컨테이너 내부에서 호스트 머신의 네트워크 주소를 참조할 수 있다.

 

 

Prometheus 실행

docker run -d --name=prometheus -p 9090:9090 -v /<prometheus 파일이 작성된 경로>/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus

 

 

 

서버 접속

localhost:9090 에 접속하면 프로메테우스 서버에 접속할 수 있다!

 

상단 메뉴에서 Status > Targets에 접속하여 스프링 애플리케이션의 매트릭스를 수집하고 있는것을 확인 할 수 있다

(나오지 않는다면 스프링 애플리케이션을 Run하고 있는지 확인하자)

 

 

서버가 실행중이면 State가 UP 이고 서버가 동작 중이지않으면 DOWN 상태이다.

 

 

---

 

Grafana 란?

Prometheus에서 수집한 데이터를 시각적으로 표현하는 대시보드 도구이다.

모니터링 데이터를 한눈에 볼 수 있도록 그래프와 차트를 제공하고 알림 기능을 제공하여 모니터링을 강화할 수 있다.

 

핵심 기능

 

• Prometheus와 연동하여 메트릭 데이터 시각화
• 대시보드(Dashboard) 기능 제공 (CPU, 메모리 사용량, API 응답 속도 등)
• 경고(Alerting) 시스템 지원
• 다양한 데이터 소스 지원 (Prometheus, MySQL, Elasticsearch 등)

주요 기능

 

• 대시보드 생성
  • Grafana는 다양한 그래프, 차트, 게이지 등을 사용하여 데이터를 시각적으로 표현할 수 있는 대시보드를 생성할 수 있다.
• 다양한 데이터 소스 지원
  • Prometheus, InfluxDB, Graphite, Elasticsearch, MySQL, PostgreSQL 등 여러 데이터 소스를 지원하며, 이를 통해 다양한 시스템과 애플리케이션의 데이터를 통합하여 시각화할 수 있다.
• 알림 기능
  • 조건을 설정하여 이메일, Slack, PagerDuty 등 다양한 채널을 통해 알림을 보내며, 시스템 상태를 실시간으로 모니터링하고 문제 발생 시 즉시 대응할 수 있다.
• 플러그인 지원
  • 플러그인 아키텍처를 지원하여 새로운 데이터 소스나 시각화 유형을 추가하는 등 기능을 확장할 수 있다.
• 사용자 관리
  • 사용자 관리 기능을 통해 대시보드와 데이터 소스에 대한 접근 권한을 설정하고, 팀 내 협업과 데이터 보안을 강화할 수 있다.

 

 

 

기본 설정 및 사용법

Grafana 설치

docker run -d -p 3000:3000 grafana/grafana

 

localhost:3000 접속

 

실행 후 localhost:3000 포트로 접속하면 grafana에 접속할 수 있다!

기본 계정과 비밀번호는 기본적으로 admin으로 설정으로 되있다.

admin을 입력해 접속하면된다.

 

Prometheus 를 데이터 소스로 추가

Grafana 메인화면 → Configuration → Data Sources → Add data source

 

 

 

 

Name을 입력한 Contact에 Prometheus Server URL 을 입력한다. 여기서는 host.docker.internal을 사용한다.
(스프링 애플리케이션이 호스트 PC에서 실행되어 접근하기 위함)

save 후 저장해준다.

 

대시보드 추가

import a dashboard 를 선택해준다.

 

19004 를 import 해준다.

 

19004 는 grafana에서 제공하는 Spring Boot 3용 대시보드이다. 

 

사용할 prometheus 설정

 

Load 한 다음 위에서 생성한 Prometheus 데이터 소스를 선택하고 import 해주면 대시보드가 생성된다.

 

대시보드 생성 성공

 

정상적으로 대시보드가 생성되어 모니터링이 가능해졌다!

 

---

Spring Boot Actuator + Prometheus + Grafana의 전체 흐름

1. Spring Boot Actuator가 애플리케이션 상태 및 메트릭 제공
2. Prometheus가 Actuator의 /actuator/prometheus 엔드포인트에서 메트릭을 수집하고 저장
3. Grafana가 Prometheus 데이터를 시각적으로 표현하여 대시보드 제공

 

---

요약

 

• Spring Boot Actuator: 애플리케이션의 상태 및 성능 메트릭 제공
• Prometheus: Actuator에서 메트릭을 수집하고 저장하는 시계열 DB
• Grafana: Prometheus 데이터를 기반으로 대시보드를 생성하여 시각화