Prometheus + Grafana 설정 시 사용한 주소 정리

Spring Boot, Prometheus, Grafana를 연동하면서 여러 URL을 다뤘다.
특히 macOS·Linux·Windows·Docker Desktop 환경 차이 때문에
처음에는 localhost 주소로 접근이 안 되는 문제가 있었고,
해결 과정에서 왜 특정 주소를 써야만 하는지 자연스럽게 알게 되었다.

이 글에서는 프로젝트 구축 과정에서 실제로 사용한 주소들을 정리한다.

---

1. Spring Boot Actuator 주소

✔ http://localhost:8081/actuator/prometheus

Spring Boot가 Prometheus에게 제공하는 메트릭 엔드포인트.

• Prometheus는 push 방식이 아니라 pull 방식
• 즉, Prometheus가 이 URL로 직접 접근해서 메트릭을 가져감
• actuator 서버를 포트 8081로 분리해둬서 API 포트(8080)와 충돌 없음

Spring Boot에서 확인 가능한 예시 메트릭:

 

http_server_requests_seconds_bucket
jvm_memory_used_bytes
hikaricp_connections_active

Prometheus가 정상적으로 pull 중인지 확인할 때 가장 먼저 열어보는 URL이다.

---

2. Prometheus UI 주소

✔ http://localhost:9090

Prometheus 웹 콘솔.

여기서 가능:

• PromQL 쿼리 테스트
• 메트릭이 잘 수집되는지 확인
• Targets(스크랩 대상) 정상 상태 확인

Prometheus Target 메뉴 →
✔ UP 이면 정상
✔ DOWN이면 Spring Boot에서 데이터를 못 가져오고 있는 상태

---

3. Grafana UI 주소

✔ http://localhost:3000

Grafana 대시보드 접속 주소.

여기서:

• Prometheus 데이터소스 등록
• 패널 생성
• PromQL 입력
• Latency·Error Rate·Heap 등 시각화 진행

로그인 기본 계정

ID: admin
PW: admin

home 화면

Data sources -> prometheus 선택 후 Connection에 http://prometheus:9090를 입력
(http://prometheus:9090는 spring boot에서 지정)

마지막으로 하단의 Save & test 클릭

Dashboards에서 프로젝트에 추가한 spring-boot-dashboard.json의 설정대로 값 확인 가능

---

4. Prometheus → Spring Boot 스크랩 주소

여기서 가장 큰 함정이 있었고, 처음에는 이 문제로 메트릭 수집이 되지 않았다.

---

❌ 처음 시도한 잘못된 주소

localhost:8081

Docker 내부에서 Prometheus 컨테이너가
호스트의 localhost로 접근하려고 하면 접근이 불가능하다.

왜냐하면…

Docker 컨테이너 내부에서 바라보는 localhost는 “컨테이너 내부 자체”를 의미하기 때문

즉,
Prometheus 컨테이너의 localhost != Windows Host OS localhost

---

✔ 최종적으로 사용한 주소

host.docker.internal:8081

Windows·Mac 기준,
Docker 컨테이너가 Host OS에 접근하기 위한 공식 엔드포인트이다.

Prometheus 설정(prometheus.yml) 최종본:

scrape_configs:
  - job_name: 'musicplace-backend'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['host.docker.internal:8081']

이 설정을 추가하고 나서야
Prometheus가 Spring Boot의 메트릭을 정상적으로 가져가기 시작했다.

---

5. 각 주소가 실제로 참여하는 “데이터 흐름”

 

브라우저 → Grafana → Prometheus → Spring Boot → Prometheus DB → Grafana

그 흐름에서 주소가 쓰이는 위치는 아래와 같다.

역할주소설명

Spring Boot 메트릭 노출	http://localhost:8081/actuator/prometheus	Prometheus가 pull하는 메트릭 엔드포인트
Prometheus Web UI	http://localhost:9090	PromQL 쿼리 테스트, 타겟 상태 확인
Grafana Web UI	http://localhost:3000	대시보드 생성 및 시각화
Prometheus → Spring Boot	host.docker.internal:8081	Docker 환경에서 Host Spring Boot에 접근하는 실제 스크랩 대상 주소

특히
localhost:8081 → ❌
host.docker.internal:8081 → ✔

이 부분이 이번 구성에서 가장 중요한 포인트였다.

---

6. 연결 문제를 해결하며 확인했던 주소 체크리스트

모니터링이 정상 동작하는지 확인하기 위해 다음 순서로 점검했다.

---

① Spring Boot 메트릭 직접 확인

http://localhost:8081/actuator/prometheus

잘 뜨면 Spring Boot 측은 정상.

---

② Prometheus Target 상태 확인

http://localhost:9090/targets

여기서

• UP이면 Spring Boot → Prometheus 연결 완료
• DOWN이면 주소 문제 or port 문제

처음에는 DOWN이었고
타겟을 host.docker.internal:8081로 바꾸고 해결됨.

---

③ Prometheus에서 직접 메트릭 검색

http://localhost:9090/graph

예: http_server_requests_seconds_bucket

이 지표가 보이면 histogram 설정도 정상적으로 활성화된 상태.

api 호출을 2~3번 진행 후 확인

---

④ Grafana에서 데이터 소스 상태 확인

Grafana → Data sources → Prometheus → “Test”

"Success"면 Grafana → Prometheus 연결 완료.

---

⑤ Grafana 패널에서 PromQL 쿼리 실행

예: Error Rate, Latency(P90), RPS 등

여기까지 데이터가 나오면 전체 모니터링 파이프라인이 완성된 것이다.

---

최종 주소 정리표

 

http://localhost:8081/actuator/prometheus	Spring Boot 메트릭	Actuator Prometheus exporter
host.docker.internal:8081	Prometheus Scrape Target	Docker → Host OS 접속 주소
http://localhost:9090	Prometheus Web UI	PromQL, Targets 확인
http://localhost:3000	Grafana Web UI	대시보드, 차트, 시각화