필사 모드: 질문에 답하는 Prometheus 메트릭 설계 — 타입 선택, 카디널리티 예산, rate 와 분위수의 함정

# 나쁨 — 마지막 요청의 지연 시간만 남는다. 분위수도 평균도 계산할 수 없다
from prometheus_client import Gauge

last_latency = Gauge("http_request_duration_seconds", "요청 처리 시간")

def handle(req):
    t0 = time.monotonic()
    resp = process(req)
    last_latency.set(time.monotonic() - t0)   # 앞선 값들은 전부 사라진다
    return resp

# 좋음 — 히스토그램은 모든 관측을 버킷에 누적한다
from prometheus_client import Counter, Histogram

REQUESTS = Counter(
    "http_requests_total", "총 요청 수",
    ["method", "route", "status_class"],
)
LATENCY = Histogram(
    "http_request_duration_seconds", "요청 처리 시간",
    ["method", "route"],
    buckets=(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0),
)

def handle(req):
    route = req.route_template          # "/v1/orders/:id" — 실제 ID 가 아니다
    with LATENCY.labels(req.method, route).time():
        resp = process(req)
    REQUESTS.labels(req.method, route, f"{resp.status // 100}xx").inc()
    return resp

JOB_RUNS = Counter("batch_job_runs_total", "배치 실행 횟수", ["job", "result"])
JOB_LAST_SUCCESS = Gauge("batch_job_last_success_timestamp_seconds", "마지막 성공 시각", ["job"])

def run_job(name, fn):
    try:
        fn()
        JOB_RUNS.labels(name, "success").inc()
        JOB_LAST_SUCCESS.labels(name).set(time.time())
    except Exception:
        JOB_RUNS.labels(name, "failure").inc()
        raise

http_request_duration_seconds_bucket
  route          120개 (라우트 템플릿)
  method           5개
  le              11개 (버킷 경계 + Inf)
  instance        40개 (파드 수)
  ------------------------------------
  = 120 * 5 * 11 * 40 = 264,000 시계열

여기에 _sum 과 _count 가 추가된다
  120 * 5 * 40 * 2 = 48,000
  ------------------------------------
합계 약 312,000 시계열 — 메트릭 하나에서

# 시계열이 가장 많은 메트릭 상위 10개
topk(10, count by (__name__)({__name__=~".+"}))

# 특정 메트릭에서 어떤 레이블이 카디널리티를 만드는가
count(count by (route) (http_requests_total))
count(count by (instance) (http_requests_total))
count(count by (status) (http_requests_total))

# 전체 활성 시계열 추이 — 계단식으로 뛰면 새 레이블이 들어온 것이다
prometheus_tsdb_head_series

# 스크레이프 대상별로 몇 개의 샘플을 주는가 (상한을 넘으면 스크레이프가 거부된다)
topk(20, scrape_samples_scraped)

# prometheus.yml
scrape_configs:
  - job_name: checkout-api
    sample_limit: 20000              # 이 대상이 이보다 많이 주면 스크레이프 실패로 처리
    label_limit: 24
    label_value_length_limit: 256
    scrape_interval: 15s
    metric_relabel_configs:
      # 사고 대응용 — 문제가 된 레이블을 수집 시점에 지운다.
      # labeldrop 이 아니라 replace 로 빈 값을 넣는 이유: labeldrop 은
      # 레이블 "이름"만 보고 매칭해서 이 job 의 모든 메트릭에서 user_id 를
      # 지운다. 아래처럼 쓰면 http_requests_total 에서만 지울 수 있다.
      # 빈 값 레이블은 Prometheus 데이터 모델에서 없는 레이블과 같다.
      - source_labels: [__name__]
        regex: 'http_requests_total'
        target_label: user_id
        replacement: ''
        action: replace
      # 아예 필요 없는 메트릭은 버린다
      - source_labels: [__name__]
        regex: 'go_gc_duration_seconds.*|python_gc_.*'
        action: drop

# 위험 — 스크레이프 간격이 15s 일 때 [20s] 는 샘플이 1개인 순간이 생긴다
rate(http_requests_total[20s])

# 안전 — 스크레이프 간격의 4배 이상. 알림에는 [5m] 이상을 권한다
rate(http_requests_total[1m])
rate(http_requests_total[5m])

# 틀림 — 카운터를 먼저 더하면 인스턴스 재시작(리셋)이 감지되지 않는다
rate(sum(http_requests_total) by (route)[5m:])

# 맞음 — rate 를 먼저, 집계는 그다음
sum(rate(http_requests_total[5m])) by (route)

# 그래프가 계속 우상향하는 직선이 나온다. 아무 정보도 없다
http_requests_total

# 초당 증가율 — 이것이 보고 싶었던 값이다
sum(rate(http_requests_total[5m])) by (route)

# 특정 구간의 총 증가량 — 알림 문구에 쓰기 좋다
sum(increase(http_requests_total{status_class="5xx"}[1h])) by (route)

# 틀림 — le 를 버리면 버킷이 뭉개져서 의미 없는 숫자가 나온다
histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (route))

# 맞음 — le 는 반드시 남긴다
histogram_quantile(0.99,
  sum(rate(http_request_duration_seconds_bucket[5m])) by (le, route)
)

# 진단 — Inf 버킷과 마지막 유한 버킷의 비율을 본다
sum(rate(http_request_duration_seconds_bucket{le="+Inf"}[5m])) by (route)
-
sum(rate(http_request_duration_seconds_bucket{le="10.0"}[5m])) by (route)

# 틀림 — 분위수는 산술 평균이 성립하지 않는다
avg(histogram_quantile(0.99, ...))

# 맞음 — 버킷 카운터를 먼저 합치고 나서 분위수를 구한다
histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: checkout-api
    # 네이티브 히스토그램 스크레이프는 명시적 opt-in
    scrape_native_histograms: true
    static_configs:
      - targets: ['checkout-api:8000']

# 고정 버킷: _bucket 시계열에 le 레이블
histogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le, route))

# 네이티브 히스토그램: le 없이 메트릭 자체를 넘긴다
histogram_quantile(0.99, sum(rate(http_request_duration_seconds[5m])) by (route))

# rules/http.yml
groups:
  - name: http_sli
    interval: 30s
    rules:
      # 계층 1 — 원본에서 한 번만 집계한다
      - record: route:http_requests:rate5m
        expr: sum(rate(http_requests_total[5m])) by (route)

      - record: route:http_requests_errors:rate5m
        expr: sum(rate(http_requests_total{status_class="5xx"}[5m])) by (route)

      # 계층 2 — 계층 1 을 참조한다. 원본을 다시 스캔하지 않는다
      - record: route:http_error_ratio:rate5m
        expr: |
          route:http_requests_errors:rate5m
            /
          route:http_requests:rate5m

      - record: route:http_request_duration_seconds:p99_rate5m
        expr: |
          histogram_quantile(0.99,
            sum(rate(http_request_duration_seconds_bucket[5m])) by (le, route)
          )

      # 서비스 전체 — 라우트 차원을 없앤 요약
      - record: service:http_error_ratio:rate5m
        expr: |
          sum(rate(http_requests_total{status_class="5xx"}[5m]))
            /
          sum(rate(http_requests_total[5m]))

# 문법 검사
promtool check rules rules/http.yml

# 단위 테스트 — 입력 시계열을 주고 기대값을 검증한다
promtool test rules tests/http_test.yml

# 전체 설정 검사
promtool check config prometheus.yml

# tests/http_test.yml
rule_files:
  - ../rules/http.yml

evaluation_interval: 30s

tests:
  - interval: 15s
    input_series:
      - series: 'http_requests_total{route="/v1/orders", status_class="2xx"}'
        values: '0+150x40'
      - series: 'http_requests_total{route="/v1/orders", status_class="5xx"}'
        values: '0+3x40'
    promql_expr_test:
      - expr: route:http_error_ratio:rate5m
        eval_time: 8m
        exp_samples:
          - labels: 'route:http_error_ratio:rate5m{route="/v1/orders"}'
            value: 0.0196078431372549