Prometheus와 Grafana 활용한 Spring Boot 모니터링 설계하기

Intro

이번 글에서는 Docker Compose를 활용해 Prometheus와 Grafana 환경을 설정하고,

Spring Boot 애플리케이션의 모니터링을 구성하는 방법을 다룬다.

 

 

Docker Compose로 Prometheus와 Grafana 실행

Prometheus와 Grafana를 컨테이너로 실행하기 위해 아래와 같은 docker-compose.yml 파일을 작성한다.

 

docker-compose.yml

services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    user: "65534:65534"
    volumes:
      - ./prometheus/config:/etc/prometheus
      - ./prometheus/data:/prometheus/data
    ports:
      - "9090:9090"
    command:
      - '--web.enable-lifecycle'
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--web.console.libraries=/etc/prometheus/console_libraries'
      - '--web.console.templates=/etc/prometheus/consoles'
    networks:
      - monitoring

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    user: "472:472"
    ports:
      - "3000:3000"
    volumes:
      - ./grafana/data:/var/lib/grafana
    networks:
      - monitoring

networks:
  monitoring:
  	name: monitoring
    driver: bridge

 

command

• ./prometheus/config:/etc/prometheus
  호스트의 config 디렉터리를 컨테이너 내부의 /etc/prometheus로 마운트해 설정 파일을 제공한다.
• --web.enable-lifecycle
  HTTP 요청으로 Prometheus 설정을 리로드 할 수 있도록 활성화한다.
• --config.file=/etc/prometheus/prometheus.yml
  사용할 설정 파일 경로를 지정한다.
• --web.console.libraries 및 --web.console.templates
  Prometheus 콘솔 템플릿과 라이브러리 경로를 설정한다.

 

주의사항

sudo chown -R 65534:65534 /prometheus/data

Prometheus는 기본적으로 nobody 사용자로 실행된다.

따라서 호스트의 디렉토리 소유권을 Prometheus의 UID와 GID에 맞추면 권한 문제를 해결할 수 있다.

 

sudo chown -R 472:472 ./grafana/data

Grafana는 기본적으로 비-루트 사용자로 실행된다.
따라서 호스트의 디렉토리 소유권을 Grafana의 UID와 GID에 맞추면 권한 문제를 해결할 수 있다.

 

 

Prometheus 설정

Prometheus는 설정 파일(prometheus.yml)을 통해 모니터링 대상, 데이터, 수집 주기, 알람 규칙 등을 정의한다.

아래는 Prometheus의 기본적인 설정 예제이며, 이를 통해 주요 항목들을 살펴보겠다.

 

prometheus.yml

global:
  scrape_interval: 15s
  scrape_timeout: 15s
  evaluation_interval: 2m

  external_labels:
    monitor: 'system-monitor'
  
  query_log_file: query_log_file.log

rule_files:
  - "rule.yml"

scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets:
          - "prometheus:9090"
  - job_name: "springboot"
    metrics_path: "/actuator/prometheus"
    scheme: 'http'
    scrape_interval: 5s
    static_configs:
      - targets:
          - "localhost:8080"

 

global

• scrape_interval
  데이터를 수집하는 주기이며 기본값은 15초로 설정되어 있다.
• evaluation_interval
  알람 규칙을 평가하는 주기이며 여기서는 2분마다 평가된다.
• query_log_file
  Prometheus의 쿼리 로그 파일 경로를 지정한다.
• external_labels
  외부 시스템과의 통합에서 사용하는 라벨이다.
  예를 들어, 아래에서 정의한 system-monitor 그룹명이 이에 해당된다.
• scrape_timeout
  데이터를 수집하는 데 소요될 최대 시간이며 기본값은 15초로 설정되어 있습니다.

 

rule_files
Prometheus의 알림 규칙을 정의한 파일을 참조한다.
예를 들어, 파일에 알림 규칙을 작성하고, 이를 Prometheus에서 사용한다.

 

Scrape Configs
Prometheus가 데이터를 수집할 타켓과 방법을 정의한다.

 

• Prometheus 자체 모니터링
  • job_name: "prometheus"
    Prometheus 자체를 모니터링한다.
  • targets
    Prometheus 서버의 주소를 지정한다.
• Spring Boot 애플리케이션 모니터링
  • job_name: "springboot"
    Spring Boot 애플리케이션의 메트릭을 수집한다.
  • metrics_path: /api/actuator/prometheus
    Spring Boot Actuator를 통해 Prometheus 포맷의 메트릭을 노출한다.
  • scheme: 'http'
    HTTP 프로토콜을 사용한다.
  • scrape_interval: 5s
    이 타겟에 대해 데이터를 수집하는 주기를 5초로 설정한다.
  • targets
    모니터링 대상의 IP 주소와 포트를 설정한다.

 

 

Prometheus Alerting Rule 설정

Prometheus는 Alerting Rule을 통해 특정 조건을 감지하고 알람을 생성할 수 있다.

 

이 알람은 Alert Manager를 통해 Slack, Email 등으로 전송되며,

시스템 문제를 빠르게 파악하고 대응하는 데 유용하다.

 

rule.yml

groups:
  - name: system-monitor
    rules:
      - alert: InstanceDown
        expr: up == 0
        for: 5m
        labels:
          severity: page
        annotations:
          summary: "Instance {{ $labels.instance }} down"
          description: "{{ $labels.instance }} of job {{ $labels.job }} has been down for more than 5 minutes."

      - alert: APIHighRequestLatency
        expr: api_http_request_latencies_second{quantile="0.5"} > 1
        for: 10m
        annotations:
          summary: "High request latency on {{ $labels.instance }}"
          description: "{{ $labels.instance }} has a median request latency above 1s (current value: {{ $value }}s)"

 

1. groups
알림 규칙을 그룹으로 묶는다.

 

2. InstanceDown

• expr: up == 0
  타깃 인스턴스가 다운되었을 때를 감지한다.
• for: 5m
  5분 이상 지속되면 알림이 발생한다.
• labels & annotaions
  severity : 알림의 심각도를 나타내며, 여기서는 page로 설정되어 즉각적인 조치가 필요함을 의미한다.
  summary 및 description : 알림에 대한 상세 정보를 제공한다.

 

3. APIHighRequestLatency

• expr: api_http_request_latencies_second {quantile="0.5"} > 1
  API의 요청 지연 시간이 1초를 초과했을 때 감지한다.
• for : 10m
  10분 이상 지속되면 알림이 발생한다.
• annotaions
  현재 요청 지연 시간을 포함한 메세지를 제공한다.

 

 

Spring Boot에서 Actuator와 Micrometer 설정

Spring Boot 애플리케이션에서 Prometheus와 같은 모니터링 도구를 통합하려면

Actuator와 Micrometer를 사용해 애플리케이션의 메트릭 데이터를 노출해야 한다.

 

아래는 build.gradle에서 Actuator와 Micrometer를 설정하는 예제다.

 

build.gradle

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

 

Actuator Endpoint 활성화

application.yml에 Prometheus 엔드포인트를 활성화한다.

 

application.yml

management:
  endpoints:
    web:
      exposure:
        include: prometheus, health, info
  metrics:
    tags:
      application: ${spring.application.name}

 

1. management.endpoints.web.exposure.incldue

• Actuator의 노출할 엔드포인트를 정의한다.
• Prometheus와의 연동을 위해 반드시 prometheus 엔드포인트가 포함되어야 한다.
• 기본적으로 Prometheus는 /actuator/prometheus 경로를 통해 데이터를 수집한다.
• 여기서는 Prometheus 메트릭, 애플리케이션 상태(health), 애플리케이션 정보(info)를 포함한다.

 

2. management.metrics.tags

• 모든 메트릭 데이터에 공통적으로 적용될 태그를 정의한다.
• 이를 통해 Prometheus 대시보드에서 애플리케이션별 메트릭 데이터를 쉽게 필터링할 수 있다.
• 여기서는 application 태그에 애플리케이션 이름(spring.application.name)을 동적으로 설정한다.

 

Prometheus 메트릭 확인

브라우저에서 http://localhost:8080/actuator/prometheus에 접근해 메트릭 데이터를 확인한다.

 

 

Grafana 대시보드 구성

 

데이터 소스 추가

Grafana 대시보드에서 Prometheus를 데이터 소스로 추가한다.

 

1. Grafana에 로그인 (http://localhost:3000)

• 초기 아이디 & 비밀번호 : admin

 

2. DATA SOURCES 클릭

 

3. Prometheus 선택 후 URL에 http://prometheus:9090 입력

 

4. Save & Test를 클릭해 설정을 저장하고 연결이 성공적으로 이루어졌는지 확인

 

대시보드 템플릿 활용

Grafana 공식 사이트에서 제공하는 템플릿을 활용하면 간단히 대시보드를 구성할 수 있다.

원하는 템플릿 ID를 검색한 뒤, Grafana의 Import 기능을 사용해 대시보드를 불러오면 된다.

 

이번 포스팅에서는 Spring Boot 3.x Statistics 템플릿을 사용한다.

Spring Boot 3.x Statistics 와 관련된 내용은 아래 URL를 참고하자.

 

Spring Boot 3.x JVM 통계, Grafana 대시보드로 분석하기

Spring Boot 3.x JVM 통계, Grafana 대시보드로 분석하기

 

1. DashBoard 클릭

 

2. New 클릭 후 Import 클릭

 

3. 아래 URL 접속 후 Copy ID to clipboard 클릭

Spring Boot 3.x Statistics

Spring Boot 3.x Statistics | Grafana Labs

 

4. 복사된 ID를 입력 후 Load 클릭

 

5. Select a Prometheus data source 입력란을 클릭 후, 등록한 Prometheus Data Source를 선택한 뒤 Import를 클릭

 

6. 아래와 같은 화면이 나타나면 설정이 성공적으로 완료

 

참고 자료 :

프로메테우스(Prometheus) & 그라파나(Grafana) 알아보기

프로메테우스(Prometheus) & 그라파나(Grafana) 알아보기

 

Prometheus Official Docs - Installation

Installation | Prometheus

 

Prometheus Official Organization - Prometheus docker container shouldn't run as user nobody

Prometheus docker container shouldn't run as user nobody · Issue #3441 · prometheus/prometheus

 

Grafana Official Docs - Installaion

Install Grafana | Grafana documentation