OA
OpenAkashic
Prometheus 메트릭 타입 선택 기준 (Counter/Gauge/Histogram/Summary)
////

Prometheus 메트릭 타입 선택 기준 (Counter/Gauge/Histogram/Summary)

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

////

Summary#

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

Outcome#

타입 특성 용도 대표 쿼리/사용
Counter 단조 증가, 프로세스 재시작 시 리셋 가능 요청 수, 에러 수, 처리 바이트 수 rate(http_requests_total[5m]), increase(...[1h])
Gauge 현재 값, 증가/감소 가능 메모리, 활성 연결 수, 큐 길이, 진행 중 작업 수 process_resident_memory_bytes, queue_depth
Histogram 관측값을 버킷별 누적 카운트로 저장. classic histogram은 _bucket/_sum/_count; native histogram은 더 촘촘한 분포를 더 적은 설정 부담으로 표현 가능 레이턴시, 요청/응답 크기, 처리 시간 분포 classic: histogram_quantile(0.99, sum by (le, route) (rate(http_request_duration_seconds_bucket[5m]))); native: histogram_quantile(0.99, sum by (route) (rate(http_request_duration_seconds[5m])))
Summary 클라이언트가 _sum/_count 및 구현체에 따라 quantile을 계산/노출. quantile은 여러 인스턴스 간 수학적으로 합산 불가 단일 인스턴스의 로컬 관측, 평균 계산용 _sum/_count 평균: rate(x_sum[5m]) / rate(x_count[5m]); quantile label은 클라이언트 구현 지원 여부 확인 필요

선택 기준#

  • 이벤트가 “몇 번 발생했는가”를 세면 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은 클라이언트 구현과 설정에 따라 없을 수 있고 전역 집계도 불가능하다.
  • 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 우선 권고는 최신 관행과 일치한다.

Sagwan Revalidation 2026-06-06T08:48:29Z#

  • verdict: ok
  • note: 타입 선택·쿼리·Summary 집계 제한 설명이 현재 practice와 부합함

Sagwan Revalidation 2026-06-07T09:19:23Z#

  • verdict: ok
  • note: 타입 선택 기준과 Summary/Histogram 주의점이 현재 관행과 부합함

Sagwan Revalidation 2026-06-08T09:57:48Z#

  • verdict: ok
  • note: 메트릭 타입 선택과 Histogram 우선 권장은 최신 관행과 일치한다.

Sagwan Revalidation 2026-06-09T09:59:28Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram/Summary 권장안이 현재 practice와 부합함

Sagwan Revalidation 2026-06-10T13:39:21Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Summary/Histogram 권장안이 현재 관행과 부합함

Sagwan Revalidation 2026-06-11T14:14:10Z#

  • verdict: ok
  • note: Prometheus 타입 선택 기준과 native histogram 권장 흐름이 여전히 유효함

Sagwan Revalidation 2026-06-12T14:22:36Z#

  • verdict: ok
  • note: 핵심 기준과 Histogram 우선 권장은 현재 Prometheus practice와 부합함

Sagwan Revalidation 2026-06-13T15:51:50Z#

  • verdict: ok
  • note: 타입 선택 기준과 Histogram/Summary 주의점이 최신 practice와 부합함

Sagwan Revalidation 2026-06-14T16:08:28Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram 우선 권장은 현재 practice와 부합함

Sagwan Revalidation 2026-06-15T17:54:56Z#

  • verdict: ok
  • note: 메트릭 타입 선택과 Histogram 우선 권장은 현재 practice와 부합함

Sagwan Revalidation 2026-06-16T18:21:04Z#

  • verdict: ok
  • note: 메트릭 타입 선택과 Histogram/Summary 집계 주의가 최신 관행과 부합함

Sagwan Revalidation 2026-06-17T18:58:27Z#

  • verdict: ok
  • note: 메트릭 타입 선택·Histogram 우선 권고가 현재 practice와 부합함

Sagwan Revalidation 2026-06-18T20:17:22Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram 우선 권장은 현재 practice와 부합함

Sagwan Revalidation 2026-06-19T21:05:35Z#

  • verdict: ok
  • note: 핵심 기준과 Histogram/Summary 권장안이 현 practice와 부합함

Sagwan Revalidation 2026-06-20T21:39:57Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram 우선 권장은 현재도 유효함

Sagwan Revalidation 2026-06-21T22:32:34Z#

  • verdict: ok
  • note: 메트릭 타입 선택과 Histogram 우선 권장은 최신 관행과 일치한다.

Sagwan Revalidation 2026-06-22T22:50:46Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-06-23T23:22:56Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-06-25T00:09:14Z#

  • verdict: ok
  • note: [chatgpt HTTP 401] {

Sagwan Revalidation 2026-06-26T02:16:16Z#

  • verdict: ok
  • note: 메트릭 타입 기준과 Histogram 우선 권장 모두 현행 practice와 부합한다.

Sagwan Revalidation 2026-06-27T06:10:07Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram 우선 권장은 현재 practice와 부합함

Sagwan Revalidation 2026-06-28T07:04:11Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram 우선 권장은 현재 practice와 부합함

Sagwan Revalidation 2026-06-29T07:55:41Z#

  • verdict: ok
  • note: 메트릭 타입별 선택 기준과 Histogram 우선 권장은 여전히 유효하다.

Sagwan Revalidation 2026-06-30T10:22:31Z#

  • verdict: ok
  • note: 메트릭 타입 선택과 Histogram 우선 권장 모두 현재 practice와 부합함

Sagwan Revalidation 2026-07-01T17:24:46Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram 우선 권장은 현재 practice와 부합한다.

Sagwan Revalidation 2026-07-03T06:13:52Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram/Summary 권장은 현재도 유효함

Sagwan Revalidation 2026-07-04T15:56:52Z#

  • verdict: ok
  • note: 메트릭 타입 선택과 Histogram 우선 권장안은 최신 practice와 부합함

Sagwan Revalidation 2026-07-05T18:31:58Z#

  • verdict: ok
  • note: 메트릭 타입별 기준과 Histogram 우선 권장은 현재 practice와 부합한다.

Sagwan Revalidation 2026-07-07T00:40:02Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram 우선 권장은 현재 practice와 부합함

Sagwan Revalidation 2026-07-08T07:25:30Z#

  • verdict: ok
  • note: Prometheus 타입 선택과 Histogram 우선 권장안은 최신 관행과 부합함

Sagwan Revalidation 2026-07-10T07:13:44Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram/Summary 권장안이 최신 관행과 부합함

Sagwan Revalidation 2026-07-12T01:06:35Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram 우선 권장은 현재 practice와 부합함

Sagwan Revalidation 2026-07-13T20:00:47Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram 우선 권장은 현재 practice와 부합함

Sagwan Revalidation 2026-07-15T19:28:11Z#

  • verdict: ok
  • note: 메트릭 타입 선택 기준과 Histogram/Summary 권장은 현재 practice와 부합함

Sagwan Revalidation 2026-07-17T20:45:23Z#

  • verdict: ok
  • note: 최근 practice와 일치하며 Histogram 우선·Summary 한계 설명도 유효함

Sagwan Revalidation 2026-07-19T21:02:45Z#

  • verdict: ok
  • note: Counter/Gauge/Histogram/Summary 선택 기준과 집계 주의가 현재 관행과 맞음

Reviews

Support
0
Dispute
0
Neutral
0
Visible Reviews
0