Grafana 및 prometheus 활용 #1

Grafana 및 prometheus 활용 #1

본 글에서는 Spring Boot 애플리케이션에서 Actuator와 Micrometer를 활용해 메트릭을 노출하고

Prometheus로 이를 수집한 뒤 Grafana를 통해 시각화하는 전체 흐름을 구성하는 방법을 설명합니다.

 

Spring Actuator + Prometheus + Grafana

• Spring Boot

  • Actuator와 Micrometer를 통해 애플리케이션 내부 메트릭을 생성합니다.
  • 생성된 메트릭은 HTTP 엔드포인트 를 통해 외부에 노출됩니다.

• Prometheus

  • 노출된 메트릭 엔드포인트를 주기적으로 pull 방식으로 scrape합니다.

• Grafana

  • Prometheus를 데이터 소스로 사용합니다.
  • 수집된 메트릭을 대시보드 형태로 시각화하여, 시스템 상태를 직관적으로 확인할 수 있습니다.

해당 구조를 통해 애플리케이션의 상태를 실시간으로 관찰하고,

문제 발생 시 원인을 파악할 수 있는 모니터링 환경을 구축할 수 있습니다.

 

1. Spring Actuator 및 Prometheus 의존성 추가

 

1.1 gradle 에 의존성 추가

build.gradle

// spring actuator
implementation "org.springframework.boot:spring-boot-starter-actuator"

// Micrometer 메트릭을 Prometheus 포맷으로 “export”해주는 레지스트리
runtimeOnly "io.micrometer:micrometer-registry-prometheus"

 

1.2 yml 설정

application-actuator.yml

management:
  endpoints:
    web:
      base-path: /management
      exposure:
        include: prometheus

해당 설정을 통해 Spring Boot는 /management/prometheus 엔드포인트를 외부에 노출합니다. 추후 Prometheus 서버가 해당 엔드포인트를 pull 방식으로 scrape하여 Spring Boot 애플리케이션의 메트릭 정보를 수집할 때 사용됩니다.

운영 환경에서는 메트릭 엔드포인트가 외부에 그대로 노출되는 것을 피하기 위해, base-path를 비표준 경로로 변경하거나, 내부 네트워크/IP로 접근을 제한하는 구성을 할수도 있습니다.

 

1.3 검증

yml 설정이 완료되었다면 아래 명령어를 통해 Actuator의 엔드포인트에 정상적으로 접근 가능한지 확인할 수 있습니다.

// local 환경
curl http://localhost:8080/management/prometheus

// docker 환경
curl http://127.0.0.1:포트/management/prometheus

위와 같이 Prometheus 포맷의 메트릭 정보를 확인할 수 있습니다.

 

2. Docker 를 통한 prometheus 올리기

 

2.1 Prometheus 설정 파일 작성

Docker를 통해 Prometheus를 실행하기 위해서는 Prometheus 설정 파일이 필요합니다.

prometheus.yml

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: prometheus
    metrics_path: "/management/prometheus"
    static_configs:
      - targets:["docker-container-name:port"]

Prometheus의 metrics_path는 Spring Boot Actuator에서 실제로 노출된 엔드포인트 경로와 정확히 일치해야 합니다.

Actuator의 base-path를 변경한 경우, Prometheus 설정 역시 동일하게 수정해야 합니다.

또한 targets에는 Prometheus 컨테이너 기준에서 접근 가능한 호스트 주소를 지정해야 합니다.

• Spring Boot 애플리케이션이 Docker 컨테이너로 실행 중이고 Prometheus와 동일한 Docker 네트워크에 있다면 컨테이너 이름을 사용할 수 있습니다. (위의 경우)
• 그렇지 않은 경우에는 호스트 IP 주소 또는 host.docker.internal 등을 사용해야 합니다.

 

2.2 docker-compose 에 prometheus 추가

docker-compose.yml

prometheus:
    image: prom/prometheus
    container_name: prometheus
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
      - ./monitoring/prometheus:/prometheus
    ports:
      - "9090:9090"

 

 

2.3 Spring Actuator 메트릭 scrape 확인

앞서 작성한 prometheus.yml 설정을 기반으로, 이제 Docker Compose를 통해 Prometheus를 실행합니다.

sudo docker compose up -d prometheus

정상적으로 실행될 경우 Prometheus 컨테이너가 기동되며, log 를 보면 아래와같은 Server is ready to receive web requests. 가 뜨는걸 확인할수 있습니다.

 

2.3.1 Prometheus 실행 시 발생할 수 있는 오류

위 명령어 실행 시, 아래와 같은 에러가 발생할 수 있습니다.

해당 오류는 아래와 같은 volume 설정을 사용하는 경우 발생할 수 있습니다.

- ./monitoring/prometheus:/prometheus

Prometheus는 시계열 데이터를 저장하는 TSDB와 active query 로그를 storage.tsdb.path(기본값 /prometheus) 하위에 저장합니다.

이때 내부적으로 /prometheus/data 디렉터리가 존재한다고 가정하고 파일을 생성·쓰기 때문에, Docker volume을 사용하는 경우 해당 디렉터리가 사전에 존재하지 않으면 기동 중 panic으로 종료될 수 있습니다.

 

2.3.2 해결 방법

아래와 같이 Prometheus 데이터 디렉터리를 사전에 생성하고, Prometheus 프로세스가 접근할 수 있도록 권한을 부여합니다.

# 디렉터리 생성
mkdir -p ./monitoring/prometheus/data

# Prometheus가 접근할 수 있도록 권한 부여
sudo chmod -R 777 ./monitoring/prometheus

이후 다시 Prometheus를 실행하면 정상적으로 기동됩니다.

 

3. Grafana 로 시각화 하기

 

3.1 Grafana ini 파일 추가

Grafana 또한 설정을 위한 ini 파일을 사용할 수 있습니다.

이를 통해 기본 계정 정보나 서비스 방식 등을 제어할 수 있습니다.

grafana.ini

# 배포 용
[server]
root_url = https://접속할 url
serve_from_sub_path = true

[security]
# 기본 admin 유저 이름 (기본값은 "admin")
admin_user = admin
# 기본 admin 비밀번호 (기본값은 "admin")
admin_password = admin

위 설정은 ELB 또는 Nginx를 통해 /monitoring과 같은 서브패스로 Grafana를 노출하는 경우에 사용됩니다.

로컬 개발 환경이나 단순 검증 단계에서는 해당 설정을 생략하고 기본 포트(3000)로 접근해도 무방합니다.

# local 용
[server]
http_port = 3000

[security]
admin_user = admin
admin_password = admin

 

3.2 docker-compose에 grafana 추가

이제 Docker Compose에 Grafana 서비스를 추가합니다.

grafana:
  image: grafana/grafana
  container_name: grafana
  ports:
    - "3000:3000"
  volumes:
    - ./monitoring/grafana:/var/lib/grafana
    - ./monitoring/grafana.ini:/etc/grafana/grafana.ini 

각 설정의 역할은 다음과 같습니다.

• /var/lib/grafana Grafana의 대시보드, 데이터 소스, 사용자 설정 등을 저장하는 디렉터리로, 컨테이너 재시작이나 재배포 시에도 설정을 유지하기 위해 volume으로 마운트합니다.
• /etc/grafana/grafana.ini 앞서 작성한 Grafana 설정 파일을 컨테이너에 적용합니다.

 

3.2.1 grafana 볼륨 디렉터리 권한 부여

Grafana가 기동 중 오류를 방지하기위해, Grafana 데이터 디렉터리를 사전에 생성하고, Grafana가 접근할 수 있도록 권한을 부여합니다.

# 디렉터리 생성
mkdir -p ./monitoring/grafana

# Grafana가 접근할 수 있도록 권한 부여
sudo chmod -R 777 ./monitoring/grafana

 

3.3 Grafana 실행 및 접속 확인

아래 명령어를 통해 Grafana 컨테이너를 실행합니다.

sudo docker compose up -d grafana

Grafana 컨테이너가 정상적으로 실행되었다면, 브라우저를 통해 Grafana 접속이 가능합니다.

앞서 grafana.ini에서 설정한 root_url을 사용하는 경우에는 해당 URL로 접속합니다.

root_url = https://접속할 url 또는 http://localhost:3000

정상적으로 접속되면 Grafana 로그인 화면이 표시되며, 초기 로그인 정보는 grafana.ini에 설정한 기본 관리자 계정을 사용합니다.

• ID: admin
• Password: admin

로그인에 성공하면 Grafana 대시보드 화면으로 이동하며, 이로써 Grafana 컨테이너 기동 및 기본 설정이 정상적으로 완료된 것을 확인할 수 있습니다.

 

다음 글에서는 Grafana와 Prometheus를 연결하는 방법과, 실제 모니터링에 바로 사용할 수 있는 대시보드 템플릿 적용 방법에 대해 다뤄보겠습니다.