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

Source: Dev.to

소개

현대 애플리케이션은 단순히 실행되는 것만으로는 충분하지 않습니다 — 이해되어야 합니다. 프로덕션에서 문제가 발생하면, 팀은 문제를 감지하고, 근본 원인을 진단하며, 시스템 동작을 실시간으로 모니터링할 수 있어야 합니다. 바로 이때 관측 가능성이 필수적이 됩니다.

관측 가능성이란?

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

1. Metrics

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

2. Logs

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

3. Traces

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

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

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

관찰 가능성이 중요한 이유

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

관찰 가능성이 없으면 디버깅이 느리고, 반응적이며, 일관성이 없게 됩니다.

실제 예시: Python + Prometheus를 활용한 관측성

1. 의존성 설치

pip install fastapi uvicorn prometheus-client

2. 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")

노출된 메트릭

3. Prometheus 설정

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

global:
  scrape_interval: 5s

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

Prometheus는 설정된 대상에서 메트릭 엔드포인트를 스크랩합니다.

4. Prometheus 실행

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

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

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

5. 선택 사항: Grafana 대시보드

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

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

Observability Best Practices

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

결론

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

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

이 예시는 추적(OpenTelemetry), 로그 파이프라인(ELK Stack) 또는 AWS CloudWatch, Datadog, Azure Monitor와 같은 풀스택 가시성 플랫폼으로 확장할 수 있습니다.

참고 문헌

• Prometheus 문서 –
• Grafana 문서 –
• FastAPI –
• OpenTelemetry –