Summary#

Prometheus 메트릭은 측정 대상의 성질과 집계 요구로 고른다. Counter는 누적 이벤트 수, Gauge는 현재 상태값, Histogram은 분포와 분위수의 서버측 집계, Summary는 클라이언트측 요약 통계에 적합하다. 여러 Pod/인스턴스의 분위수를 합산해야 하는 서비스에서는 Summary보다 Histogram(필요 시 native histogram 포함)을 우선 고려한다.

Outcome#

선택 기준#

• 이벤트가 “몇 번 발생했는가”를 세면 Counter를 쓴다.
• 지금 값이 얼마인지 나타내면 Gauge를 쓴다.
• SLO/레이턴시 분위수처럼 여러 인스턴스에서 분포를 합쳐야 하면 Histogram을 쓴다.
• Summary의 quantile은 인스턴스별 계산 결과라 여러 Pod 값을 합산해 전역 p95/p99를 만들 수 없다.
• Python prometheus_client를 쓰는 FastAPI 서비스에서는 Summary quantile 노출 여부를 구현체 문서로 확인해야 하며, 일반적인 HTTP latency 계측은 Histogram이 안전하다.

FastAPI 실전 예시#

동적 URL 원문(/users/123, /users/456)을 레이블로 쓰면 카디널리티가 폭발한다. 가능하면 라우트 템플릿(/users/{id}) 또는 제한된 endpoint 이름을 사용한다.

import time
from prometheus_client import Counter, Histogram

REQUEST_COUNT = Counter(
    'http_requests_total',
    'Total HTTP requests',
    ['method', 'route', 'status'],
)

REQUEST_LATENCY = Histogram(
    'http_request_duration_seconds',
    'HTTP request latency seconds',
    ['method', 'route'],
    buckets=[0.01, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0],
)

@app.middleware('http')
async def metrics_middleware(request, call_next):
    start = time.time()
    response = await call_next(request)

    route = getattr(request.scope.get('route'), 'path', None) or 'unknown'
    method = request.method
    status = str(response.status_code)

    REQUEST_LATENCY.labels(method, route).observe(time.time() - start)
    REQUEST_COUNT.labels(method, route, status).inc()
    return response

Key Points#

• Counter 원값은 누적값이므로 대시보드/알림에는 보통 rate() 또는 increase()를 쓴다.
• Gauge는 현재 상태값이며 set(), inc(), dec()가 모두 가능하다.
• Histogram은 sum by (...)로 여러 Pod를 합쳐 분위수를 추정할 수 있다. classic histogram은 le 레이블을 포함해 집계해야 한다.
• Summary quantile은 여러 인스턴스 간 합산할 수 없다. 분산 서비스의 전역 p95/p99에는 Histogram을 선택한다.
• native histogram을 사용할 수 있는 Prometheus/클라이언트 환경이라면 버킷 설계 부담을 줄일 수 있지만, 서버·클라이언트·원격 저장소 호환성을 확인해야 한다.

Caveats#

• Histogram 버킷은 SLO와 실제 레이턴시 범위를 커버해야 한다. 관측값이 대부분 +Inf 또는 마지막 버킷에 몰리면 분위수 추정 품질이 나빠진다.
• 사용자 ID, 주문 ID, raw URL, 세션 ID 같은 고카디널리티 값을 레이블에 넣지 않는다.
• FastAPI/Starlette 계측에서는 request.url.path 대신 route template 또는 bounded endpoint label을 사용한다.
• Summary를 쓰더라도 _sum/_count로 평균은 집계할 수 있지만, quantile label은 클라이언트 구현과 설정에 따라 없을 수 있고 전역 집계도 불가능하다.

Related Vault Notes#

• personal_vault/shared/reviews/r_20260425T134358Z_b29d0c.md — FastAPI 경로 레이블 카디널리티와 native histogram 보강 필요를 지적한 활성 dispute 리뷰.
• personal_vault/meta/improvement-requests/search-quality-prometheus-metric-types-counter-gauge-histogram-su-8001de.md — Prometheus metric types 검색 품질 개선 요청.

Sagwan Revalidation 2026-06-05T08:28:30Z#

• verdict: ok
• note: 메트릭 타입별 기준과 Histogram 우선 권고는 최신 관행과 일치한다.