[파이널 과제] NovelCraft 웹소설 창작 플랫폼 개발 프로젝트 Day 17

https://github.com/Hot6-NovelCraft/Hot6-NovelCraft

GitHub - Hot6-NovelCraft/Hot6-NovelCraft

개인별 배포용 레퍼지토리 [ AWS ]

https://github.com/MinWoo1995/Hot6-NovelCraft-local

GitHub - MinWoo1995/Hot6-NovelCraft-local

 

1. 오늘 한 일

오늘은 AI 이미지 생성 SDK 연동과 Kafka 설정이 완료된 상태에서, 빠져있던 Grafana 모니터링 환경을 처음부터 끝까지 구축했다.

• Spring Boot Actuator + Micrometer Prometheus 의존성 추가 및 application.yml 설정
• docker-compose.yml에 Kafka JMX Exporter 3개 추가 (kafka-1 / kafka-2 / kafka-3)
• Kafka 브로커 3개에 JMX 포트 환경변수 설정 (KAFKA_JMX_PORT: 9999, KAFKA_JMX_HOSTNAME)
• monitoring/kafka-jmx-config.yml 작성 (JMX 메트릭 수집 룰 정의)
• monitoring/prometheus.yml Kafka 스크랩 타겟 3개 추가
• Prometheus → Grafana 데이터소스 연결 (http://prometheus:9090)
• Grafana 대시보드 Import (Spring Boot 19004, Kafka 7589)
• Prometheus Targets 전체 UP 상태 확인 (novelcraft / kafka-1 / kafka-2 / kafka-3)

---

2. 트러블슈팅

2-1. Spring Boot 3.3.5에서 management.endpoint.prometheus.enabled 빨간불

문제 상황

application.yml에 아래와 같이 Prometheus 설정을 작성했더니 IDE에서 빨간불이 들어왔다.

 

 

yaml

management:
  endpoint:
    prometheus:
      enabled: true

원인 분석

Spring Boot 3.3.x에서는 enabled 속성이 deprecated 되어 해당 키 자체가 제거됐다. micrometer-registry-prometheus 의존성이 classpath에 있으면 /actuator/prometheus 엔드포인트가 자동으로 활성화되기 때문에 별도로 enabled를 선언할 필요가 없어졌다.

해결

enabled 관련 설정을 전부 제거하고 아래와 같이 정리했다.

 

 

yaml

management:
  endpoints:
    web:
      exposure:
        include: health, prometheus, metrics, info
  endpoint:
    health:
      show-details: always
  metrics:
    tags:
      application: novelcraft

의존성만 있으면 자동 활성화된다는 점을 다시 한번 확인했다.

---

2-2. GRAFANA_ADMIN_PASSWORD 환경변수 누락으로 docker-compose 실행 실패

문제 상황

docker-compose up -d 실행 시 아래 에러가 발생했다.

 

 

error while interpolating services.grafana.environment.GF_SECURITY_ADMIN_PASSWORD:
required variable GRAFANA_ADMIN_PASSWORD is missing a value: set GRAFANA_ADMIN_PASSWORD

원인 분석

기존 docker-compose.yml의 Grafana 설정이 아래와 같이 환경변수를 필수로 강제하는 방식이었다.

 

 

yaml

GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:?set GRAFANA_ADMIN_PASSWORD}

로컬에 .env 파일이 없어서 해당 변수를 찾지 못해 실행 자체가 차단됐다.

해결

프로젝트 루트에 .env 파일을 생성하고 값을 추가했다.

 

 

GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=admin

.env 파일은 민감정보가 포함될 수 있으므로 .gitignore에 등록되어 있는지 반드시 확인해야 한다.

---

2-3. Prometheus Targets에서 Kafka 타겟이 보이지 않음

문제 상황

http://localhost:9095/targets 에 접속했을 때 novelcraft 타겟만 UP 상태로 보이고 Kafka 타겟은 아예 표시되지 않았다.

원인 분석

prometheus.yml의 Kafka 스크랩 타겟을 아래와 같이 host.docker.internal로 설정했는데, Kafka JMX Exporter는 도커 컨테이너 내부에 떠있기 때문에 host.docker.internal로는 접근이 불가능했다.

 

 

yaml

# 잘못된 설정
- job_name: 'kafka'
  static_configs:
    - targets: ['host.docker.internal:5556']

Spring Boot 앱은 도커 외부(로컬)에서 실행되므로 host.docker.internal이 맞지만, JMX Exporter는 도커 네트워크 내부 서비스이므로 컨테이너 서비스명으로 접근해야 했다.

해결

prometheus.yml을 아래와 같이 컨테이너 서비스명 기준으로 수정하고 Prometheus를 재시작했다.

 

 

yaml

scrape_configs:
  - job_name: 'novelcraft'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['host.docker.internal:8080']   # 앱은 로컬 실행이므로 host.docker.internal

  - job_name: 'kafka-1'
    static_configs:
      - targets: ['kafka-1-jmx-exporter:5556']   # JMX Exporter는 도커 내부 서비스명

  - job_name: 'kafka-2'
    static_configs:
      - targets: ['kafka-2-jmx-exporter:5556']

  - job_name: 'kafka-3'
    static_configs:
      - targets: ['kafka-3-jmx-exporter:5556']

 

 

bash

docker-compose restart prometheus

재시작 후 Targets 페이지에서 kafka-1 / kafka-2 / kafka-3 모두 UP 상태를 확인했다.

---

3. 주요 구현 내용

최종 모니터링 아키텍처

 

 

Spring Boot App (로컬:8080)
    └─ /actuator/prometheus
            ↓
        Prometheus (도커:9095)
            ├─ novelcraft job   → host.docker.internal:8080
            ├─ kafka-1 job      → kafka-1-jmx-exporter:5556
            ├─ kafka-2 job      → kafka-2-jmx-exporter:5556
            └─ kafka-3 job      → kafka-3-jmx-exporter:5556
                ↓
            Grafana (도커:3000)
                ├─ Spring Boot 3.x Statistics (ID: 19004)
                └─ Kafka Exporter Overview    (ID: 7589)

docker-compose.yml 변경 사항 (팀원 영향 최소화)

기존 구조를 최대한 유지하면서 아래 항목만 추가했다.

• kafka-1 / kafka-2 / kafka-3 환경변수에 KAFKA_JMX_PORT: 9999, KAFKA_JMX_HOSTNAME 2줄 추가
• kafka-1-jmx-exporter, kafka-2-jmx-exporter, kafka-3-jmx-exporter 서비스 3개 신규 추가
• Prometheus depends_on에 JMX Exporter 3개 추가

신규 오픈 포트: 5556, 5557, 5558

monitoring/ 폴더 구조

 

 

monitoring/
├── prometheus.yml
└── kafka-jmx-config.yml

kafka-jmx-config.yml은 JMX 메트릭 수집 룰을 정의하는 파일로, 이 파일이 없으면 JMX Exporter 컨테이너가 뜨지 않는다. 팀원들이 docker-compose up 할 때 반드시 해당 파일이 있어야 하므로 함께 커밋했다.

Grafana 대시보드 결과

• Spring Boot 3.x Statistics: Uptime, Heap Used(2.9%), Non-Heap Used(17.8%), CPU Usage, Load Average 등 실시간 수집 확인
• Kafka Exporter Overview: 현재 메시지 발행/소비가 없어 No data 상태이며, 실제 트래픽 발생 시 데이터가 채워질 예정

---

4. 느낀 점

모니터링 환경 구축은 처음이라 설정 하나하나가 낯설었는데, 막상 Grafana 대시보드에 메트릭이 실시간으로 찍히는 걸 보니 뿌듯했다.

가장 헷갈렸던 부분은 도커 네트워크 개념이었다. Spring Boot 앱처럼 도커 외부에서 실행되는 서비스는 host.docker.internal로 접근해야 하고, JMX Exporter처럼 도커 내부 컨테이너는 서비스명으로 접근해야 한다는 점이 처음엔 직관적으로 와닿지 않았다. 타겟이 안 보이는 현상을 보고 직접 원인을 추적하면서 도커 네트워크 구조를 제대로 이해하게 됐다.

팀 프로젝트에서 docker-compose.yml을 수정할 때는 기존 구조를 얼마나 건드리지 않을 수 있느냐가 중요하다는 것도 느꼈다. 처음에는 과감하게 수정했다가 팀원 영향을 고려해서 최소한의 변경만 남기는 방향으로 다시 정리했는데, 공유 인프라 파일을 다룰 때는 항상 팀원 관점에서 먼저 생각해야 한다는 걸 다시 한번 깨달았다.

다음 단계로는 실제로 Kafka 메시지가 발행/소비될 때 Grafana 대시보드에서 Consumer Lag, Message In/Out per second 등이 어떻게 보이는지 확인해볼 예정이다.