관측성 실천: Python 및 Prometheus를 활용한 실제 모니터링 구현

Source: Dev.to

관측성(Observability)이란?

관측성은 시스템이 생성하는 데이터를 기반으로 시스템 내부 상태를 이해할 수 있는 능력입니다. 이는 세 가지 핵심 기둥을 중심으로 구성됩니다:

1. 메트릭(Metrics)

시스템 상태를 반영하는 수치값.
예시: 요청 지연 시간, CPU 사용량, 메모리 소비량.

2. 로그(Logs)

애플리케이션 및 시스템에서 생성되는 상세 이벤트 기록.
예시: 인증 메시지, 오류, 경고.

3. 트레이스(Traces)

서비스 간 요청을 끝‑끝까지 추적.
마이크로서비스 및 분산 시스템에서 유용.

이 세 가지를 통해 다음 질문에 답할 수 있습니다:

• 무슨 일이 일어나고 있나요?
• 왜 일어나고 있나요?
• 어디에서 실패하고 있나요?

관측성이 중요한 이유

• 문제를 조기에 감지
• 다운타임 감소
• 성능 향상
• 사용자 영향 파악
• 대규모 애플리케이션 모니터링
• 데이터 기반 의사결정

관측성이 없으면 디버깅이 느리고, 반응형이며, 일관성이 떨어집니다.

실전 예시: Python + Prometheus 로 구현하는 관측성

의존성 설치

pip install fastapi uvicorn prometheus-client

Prometheus 메트릭을 포함한 Python API

from fastapi import FastAPI
from prometheus_client import Counter, Histogram, generate_latest
from fastapi.responses import Response
import time
import random

app = FastAPI()

REQUEST_COUNT = Counter("api_requests_total", "Total number of API requests received")
REQUEST_LATENCY = Histogram("api_request_latency_seconds", "API request latency")

@app.get("/")
def home():
    REQUEST_COUNT.inc()
    with REQUEST_LATENCY.time():
        time.sleep(random.uniform(0.1, 0.5))
        return {"message": "API is running successfully"}

@app.get("/metrics")
def metrics():
    return Response(generate_latest(), media_type="text/plain")

노출되는 메트릭

Prometheus 설정

prometheus.yml 파일을 생성합니다:

global:
  scrape_interval: 5s

scrape_configs:
  - job_name: "python-api"
    static_configs:
      - targets: ["localhost:8000"]

Prometheus는 다음 엔드포인트에서 메트릭을 스크랩합니다:

Prometheus 실행

./prometheus --config.file=prometheus.yml

Prometheus UI를 열고 다음과 같은 메트릭을 조회합니다:

• api_requests_total
• rate(api_requests_total[1m])
• api_request_latency_seconds_bucket

선택 사항: Grafana 대시보드

Grafana를 사용하면 Prometheus 메트릭을 시각화할 수 있습니다. 일반적인 그래프 예시:

• 요청 속도
• CPU 및 메모리 사용량
• 오류 비율
• 지연 시간 백분위수(p95, p99)

관측성 모범 사례

• ✔ 모든 주요 엔드포인트에 계측 – 성능에 중요한 API에 메트릭을 노출합니다.
• ✔ 메트릭 이름 표준화 – 무작위이거나 구조화되지 않은 이름을 피합니다.
• ✔ 라벨(태그) 포함 – 예: status_code, endpoint, method 등으로 풍부한 컨텍스트 제공.
• ✔ 알림 설정 – 예: “95번째 백분위수 지연 시간이 500 ms를 3 분 동안 초과”.
• ✔ 모든 것을 시각화 – 대시보드는 패턴을 명확히 보여줍니다.
• ✔ 로그, 메트릭, 트레이스 결합 – 세 기둥이 모두 존재할 때 관측성이 최적화됩니다.

결론

관측성을 통해 팀은 시스템이 어떻게 동작하는지 깊이 이해할 수 있습니다. Prometheus와 FastAPI를 활용하면 다음을 지원하는 유용한 메트릭을 노출할 수 있습니다:

• 빠른 디버깅
• 향상된 성능 인사이트
• 안전한 배포
• 확장 가능한 시스템 모니터링

이 예시는 트레이싱(OpenTelemetry), 로그 파이프라인(ELK Stack) 또는 AWS CloudWatch, Datadog, Azure Monitor와 같은 전체 스택 관측성 플랫폼으로 확장할 수 있습니다.

References

• Prometheus Documentation –
• Grafana Documentation –
• FastAPI –
• OpenTelemetry –