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. 指向你的 Prometheus/Mimir。若使用 Grafana Cloud，請使用 metrics 端點
#    並在每個 curl 中加入基本認證（-u "<metrics_user>:<token>"）。
PROM=http://localhost:9090   # 或 https://prometheus-prod-XX.grafana.net/api/prom

# 1. 草擬查詢 — 例如「每個服務的 5xx 錯誤率」：
EXPR='sum(rate(http_requests_total{status_code=~"5.."}[5m])) by (service)'

# 2. 驗證語法及指標/標籤是否存在
curl -sG --data-urlencode "query=${EXPR}" \
  "$PROM/api/v1/query" | jq '.status, (.data.result|length)'
# 預期："success" 且結果數 > 0。若為 0 — 檢查標籤拼寫及擷取活動：
curl -sG --data-urlencode "match[]=http_requests_total" "$PROM/api/v1/series" | jq '.data | length'

# 3. 合理性檢查數值大小 — 開啟 Grafana Explore，貼上表達式，
#    確認數值與已知基準（k6 執行、日誌計數等）相符。

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. 選取緩慢的表達式，為其命名錄製規則名稱
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. 規則載入後，驗證新指標是否存在
curl -sG --data-urlencode "query=job:http_request_duration_p95:rate5m" \
  "$PROM/api/v1/query" | jq '.data.result | length'   # → > 0

# 3. 驗證其值與原始表達式在至少一個取樣視窗內相符
# （兩個查詢在同一時間戳應產生相同數值。）

# 4. 將儀表板面板表達式替換為錄製規則指標。

常見錯誤

• histogram_quantile 回傳 NaN → 內層聚合忘記加 by (le)
• 「無資料」→ 檢查指標是否存在（/api/v1/series）且視窗 ≥ 4 倍擷取間隔
• 速率數值錯誤 → counter 在 rate() 之前被聚合（務必先 rate()）
• 查詢逾時 → 序列數量過高；使用 topk(...) + 錄製規則 + 移除高基數標籤（參見 references/patterns.md）

資源

• PromQL 基礎
• 運算子
• 函式
• Grafana Mimir