필사 모드: 質問に答える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