FastAPI에 Grafana와 Prometheus를 적용하여 모니터링 구축하기
FastAPI 애플리케이션이 안정적으로 운영되려면 요청 수, 응답 시간, 오류율과 같은 핵심 성능 지표를 지속적으로 모니터링해야 한다.
단순한 로그 분석만으로는 실시간 데이터 추적과 시각화가 어렵기 때문에, Prometheus와 Grafana를 활용하면 보다 효율적인 모니터링 환경을 구축할 수 있다.
- Prometheus: 애플리케이션에서 메트릭을 수집하고 시계열 데이터로 저장하는 오픈소스 모니터링 도구.
- Grafana: Prometheus 데이터를 기반으로 다양한 차트를 생성하고 대시보드를 구성할 수 있는 시각화 도구.
Prometheus는 API 성능 데이터를 실시간으로 수집하고, Grafana를 통해 이를 직관적으로 분석할 수 있다.
또한, 임계값 초과 시 경고(Alert)를 설정할 수 있어 장애 대응도 용이하다.
이 글에서는 FastAPI에 Prometheus와 Grafana를 적용하여 성능을 모니터링하는 방법을 설명한다.
Prometheus & Grafana 개요
Prometheus란?
시계열(time-series) 데이터 저장 및 조회를 위한 오픈소스 모니터링 도구.
- Exporter: 애플리케이션에서 메트릭을 노출하는 역할.
- Pull 방식: Prometheus가 주기적으로 데이터를 수집하는 방식.
- 시계열 데이터: 특정 시점의 메트릭을 지속적으로 저장하고 조회할 수 있다.
- AlertManager: 설정된 조건을 기반으로 경고(알람)를 트리거한다.
Grafana란?
Prometheus 데이터를 시각적으로 표현하는 대시보드 도구.
- Panel: 데이터 시각화를 위한 그래프, 테이블 등.
- Dashboard: 여러 개의 Panel을 조합하여 생성하는 모니터링 화면.
- Data Source: Prometheus와 같은 외부 데이터 소스 연결.
FastAPI에서 Prometheus와 Grafana를 사용하는 이유
Prometheus를 이용하면 FastAPI의 요청 수, 응답 시간, 오류율 등을 모니터링할 수 있다.
Grafana를 사용하면 Prometheus에서 수집한 데이터를 직관적으로 시각화할 수 있다.
운영 환경에서 실시간 트래픽 분석과 장애 대응이 가능해진다.
FastAPI에 Prometheus 적용하기
FastAPI 프로젝트에 Prometheus Exporter 추가
- pip install prometheus-fastapi-instrumentator
from fastapi import FastAPI
from prometheus_fastapi_instrumentator import Instrumentator
app = FastAPI()
# Prometheus 메트릭 수집기 등록
Instrumentator().instrument(app).expose(app)Prometheus 설정 및 실행
Prometheus 설정 파일(prometheus.yml):
global:
scrape_interval: 15s
scrape_configs:
- job_name: "fastapi"
static_configs:
- targets: ["localhost:8000"]- Prometheus 실행:
prometheus --config.file=prometheus.yml
Prometheus 웹 UI (http://localhost:9090)에서 http_requests_total 등의 메트릭을 조회할 수 있다.
Grafana로 FastAPI 모니터링 대시보드 구축
Grafana 설치 및 실행
docker run -d -p 3000:3000 --name=grafana grafana/grafana
Grafana 웹 UI (http://localhost:3000)에 접속하여 설정을 진행한다.
Prometheus 데이터 소스 추가
- Configuration → Data Sources → Prometheus 선택
- URL: http://localhost:9090 입력 후 저장
Grafana 대시보드 생성
- 새로운 대시보드 추가 (Create Dashboard)
- Add Query → http_requests_total 입력 후 실행
- Line Chart 또는 Bar Chart로 시각화
FastAPI API 요청 및 오류 모니터링
FastAPI 요청 응답 시간 추적
- PromQL 쿼리 (엔드포인트별 평균 응답 시간 조회):
rate(http_request_duration_seconds_sum{method="GET"}[5m])
/ rate(http_request_duration_seconds_count{method="GET"}[5m])Grafana에서 위 데이터를 Line Chart로 표현하면 실시간 응답 시간 모니터링이 가능하다.
FastAPI 오류율 모니터링
- PromQL 쿼리 (5xx 오류율 조회):
sum(rate(http_requests_total{status=~"5.."}[5m]))
/ sum(rate(http_requests_total[5m]))Grafana에서 5xx 오류율을 Bar Chart로 표현하고, 임계값(예: 1%)을 초과할 경우 Alert 설정을 할 수 있다.
결론 및 운영 환경 적용 방안
- Prometheus와 Grafana를 활용하면 FastAPI의 성능 및 오류를 실시간으로 추적할 수 있다.
- 대시보드 설정을 통해 API 트래픽, 응답 속도, 오류율을 분석할 수 있으며, 서비스 안정성을 높이는 데 기여한다.
- AlertManager와 연동하면 임계값 초과 시 Slack, 이메일 등으로 알림을 받을 수 있다.
- 운영 환경에 맞춰 Prometheus 및 Grafana 설정을 최적화하여 실시간 모니터링을 강화하는 것이 중요하다.
