promql

PromQL クエリパターン

ドキュメント: https://prometheus.io/docs/prometheus/latest/querying/basics/

PromQL は、インスタントベクトル、レンジベクトル、またはスカラーを返します。

基本ルール： rate() / increase() には、スクレイプ間隔の 4 倍以上のレンジベクトルが必要です。スクレイプ間隔が 60 秒の場合は、最低でも [5m] を使用してください。

前提条件

• クエリを実行できる Prometheus / Mimir / Grafana Cloud エンドポイント（/api/v1/query または Grafana Explore 経由）
• references/patterns.md の PromQL パターンライブラリ

よくあるワークフロー

1. クエリの作成と検証

# 0. Point at your Prometheus/Mimir. For Grafana Cloud, use the metrics endpoint
#    and add basic auth (-u "<metrics_user>:<token>") to each curl below.
PROM=http://localhost:9090   # or https://prometheus-prod-XX.grafana.net/api/prom

# 1. Sketch the query — for "5xx error rate per service":
EXPR='sum(rate(http_requests_total{status_code=~"5.."}[5m])) by (service)'

# 2. Validate syntax + that the metric/labels exist
curl -sG --data-urlencode "query=${EXPR}" \
  "$PROM/api/v1/query" | jq '.status, (.data.result|length)'
# Expect: "success" and result count > 0. If 0 — check label spelling and scrape activity:
curl -sG --data-urlencode "match[]=http_requests_total" "$PROM/api/v1/series" | jq '.data | length'

# 3. Sanity-check the magnitude — open Grafana Explore, paste the expr,
#    confirm the values look right against a known ground truth (k6 run, log count, etc.)

2. コピーして使える一般的なパターン

ステータスごとのリクエストレート（rate の適用後に集約）：

sum(rate(http_requests_total{job="api"}[5m])) by (status_code)

p95 レイテンシ（内側の集約で le を保持する必要があります）：

histogram_quantile(0.95,
  sum(rate(http_request_duration_seconds_bucket[5m])) by (le, service))

ゼロ除算を防ぐエラー率：

sum(rate(http_requests_total{status_code=~"5.."}[5m]))
  / (sum(rate(http_requests_total[5m])) > 0)

完全なライブラリ（記録ルール、SLO バーンレート、オフセット、カーディナリティ調査、ネイティブヒストグラム）：references/patterns.md。

3. 遅いダッシュボードクエリを記録ルールに変換する

# 1. Pick the slow expression, give it a recording-rule name
groups:
  - name: http_request_rates
    interval: 1m
    rules:
      - record: job:http_request_duration_p95:rate5m
        expr: |
          histogram_quantile(0.95,
            sum(rate(http_request_duration_seconds_bucket[5m])) by (le, job))

# 2. After rules load, verify the new metric exists
curl -sG --data-urlencode "query=job:http_request_duration_p95:rate5m" \
  "$PROM/api/v1/query" | jq '.data.result | length'   # → > 0

# 3. Verify it matches the original expression for at least one sample window
# (Both queries should produce the same value at the same timestamp.)

# 4. Replace the dashboard panel expression with the recording-rule metric.

よくあるバグ

• histogram_quantile が NaN を返す → 内側の集約で by (le) を忘れています
• 「データなし」→ メトリクスが存在すること（/api/v1/series）と、ウィンドウがスクレイプ間隔の 4 倍以上であることを確認してください
• レートの桁が誤っている → rate() より前にカウンターを集約しています（必ず最初に rate() を適用してください）
• クエリがタイムアウトする → 時系列の数が多すぎます。topk(...) と記録ルールを使い、カーディナリティの高いラベルを削除してください（references/patterns.md を参照）

リソース

• PromQL の基本
• 演算子
• 関数
• Grafana Mimir