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，使用指标端点
#    并在每个 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 倍
• 速率数值错误 → 计数器在 rate() 之前被聚合（始终先 rate()）
• 查询超时 → 序列数量过多；使用 topk(...) + 记录规则 + 删除高基数标签（参见 references/patterns.md）

资源

• PromQL 基础
• 运算符
• 函数
• Grafana Mimir