Prometheus & Grafana 로컬 모니터링 스택 (커스텀 Python 앱 포함)

이 프로젝트는 Grafana, Prometheus, 그리고 커스텀 메트릭을 노출하는 Python FastAPI 애플리케이션으로 구성된 로컬 모니터링 환경을 구축하는 방법을 안내합니다.

📚 개요

본 프로젝트의 목표는 다음과 같습니다:

• Prometheus를 사용하여 시계열 데이터를 수집하고 저장합니다.
• 커스텀 Python 애플리케이션에서 특정 비즈니스 로직이나 성능 관련 메트릭을 생성하고 Prometheus에 노출합니다.
• Grafana를 사용하여 수집된 메트릭을 시각화하고 대시보드를 만듭니다.
• Docker 및 Docker Compose를 사용하여 전체 스택을 쉽게 구성하고 실행합니다.

🧩 구성 요소

• Prometheus: 메트릭 수집 및 시계열 데이터베이스 (http://localhost:9090)
• Grafana: 데이터 시각화 및 대시보드 플랫폼 (http://localhost:3000)
• Python App (python_app/ 폴더): FastAPI 기반의 샘플 애플리케이션. 커스텀 메트릭을 생성하여 /metrics 엔드포인트로 노출합니다. (애플리케이션 직접 접근: http://localhost:8001, 메트릭: http://localhost:8001/metrics)
• Docker & Docker Compose: 컨테이너화 및 서비스 오케스트레이션 도구

⚙️ 사전 준비 사항

• Docker
• Docker Compose (Docker Desktop에 포함되어 있음)

🚀 설정 및 실행 방법

1. 이 저장소를 클론하거나 파일들을 로컬 머신에 다운로드합니다.
2. 루트 디렉토리 (my-monitoring/)로 이동합니다.
3. 다음 명령어를 실행하여 모든 서비스를 빌드하고 백그라운드에서 시작합니다:

   docker-compose up -d --build

   • --build 옵션은 이미지 변경사항(특히 python_app의 Dockerfile 수정 시)을 반영하여 새로 빌드합니다.

🔗 서비스 접속 정보

• Python 애플리케이션:
  • 기본 페이지: http://localhost:8001/
  • 데이터 페이지: http://localhost:8001/data
  • 메트릭 페이지: http://localhost:8001/metrics
• Prometheus: http://localhost:9090
  • 타겟 확인: Status -> Targets (prometheus, python_app 잡 확인)
  • 메트릭 쿼리: Graph 탭
• Grafana: http://localhost:3000
  • 초기 로그인: ID admin / PW admin (첫 로그인 시 비밀번호 변경 권장)
  • 데이터 소스 설정:
    1. 로그인 후 왼쪽 메뉴 ⚙️ Configuration -> Data Sources 클릭
    2. Add data source -> Prometheus 선택
    3. HTTP URL: http://prometheus:9090 입력 (Docker 내부 네트워크에서는 서비스 이름으로 접근)
    4. Save & test 클릭하여 연결 확인
  • 대시보드 생성: Python 앱에서 노출된 커스텀 메트릭(예: my_python_app_requests_total)을 사용하여 대시보드 및 패널 생성

🛠️ 주요 설정 파일

• docker-compose.yml: 전체 서비스(Grafana, Prometheus, Python 앱)의 정의, 네트워크 설정, 볼륨 마운트 등을 관리합니다.
• prometheus.yml: Prometheus의 스크레이프(scrape) 대상 및 주기를 설정합니다. 현재 Prometheus 자체와 python-app 서비스를 대상으로 설정되어 있습니다.
• python_app/Dockerfile: uv를 사용하여 Python FastAPI 애플리케이션의 Docker 이미지를 빌드합니다.
• python_app/pyproject.toml: Python 애플리케이션의 의존성 및 프로젝트 정보를 정의합니다. uv.lock 파일은 이 정보를 바탕으로 생성된 정확한 의존성 버전 정보를 담고 있습니다.

📊 python-app 예제 메트릭

• my_python_app_requests_total: 앱이 받은 총 요청 수 (레이블: method, endpoint)
• my_python_app_inprogress_requests: 현재 처리 중인 요청 수
• my_python_app_request_latency_seconds: 요청 처리 지연 시간 분포 (레이블: endpoint)

🔍 문제 해결 팁

• 각 서비스의 로그 확인: docker-compose logs <서비스_이름> (예: docker-compose logs python-app)
• 포트 충돌 확인: docker-compose.yml에 정의된 포트(3000, 8001, 9090)가 로컬 머신에서 이미 사용 중인지 확인하세요.
• Prometheus Targets 페이지에서 python-app의 상태가 UP인지 확인하세요.

✨ 다음 단계

• Python 앱에 더 다양한 커스텀 메트릭 추가하기
• Grafana에서 고급 기능 활용:
  • 변수(Variables)를 사용하여 동적 대시보드 만들기
  • 알림(Alerting) 설정하기
• 다른 유용한 Exporter 추가하기 (예: node_exporter를 통한 시스템 메트릭 수집)