mcpField
P
promql

promql

github.com/grafana云与 DevOps2958.3k 次安装1 天前更新
代码仓库

关于 promql

该技能整理 PromQL 查询模式与验证步骤，供使用 Prometheus、Mimir 或 Grafana Cloud 查询指标的用户参考。它涵盖常见聚合、延迟与错误率查询、记录规则，以及排查查询问题的方法。

主要功能

  1. 01PromQL 查询模式库
  2. 02查询语法与指标验证
  3. 03速率、延迟及错误率查询
  4. 04记录规则转换与验证
  5. 05常见查询问题排查

适用场景

  1. 01查询服务的 5xx 错误率
  2. 02计算请求速率和 p95 延迟
  3. 03将慢查询改为记录规则

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/grafana/skills --skill promql

安装后在 Claude Code 中输入/promql确认已加载。

附带文件references/patterns.md

详细介绍

PromQL 查询模式

文档：https://prometheus.io/docs/prometheus/latest/querying/basics/

PromQL 返回即时向量、范围向量或标量。

黄金法则：rate() / increase() 要求范围向量长度 ≥ 抓取间隔的 4 倍。抓取间隔为 60s → 至少使用 [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）

资源

评论

支持 Markdown