PromQL 在查什么
PromQL 的查询对象是时间序列：一条序列由指标名加一组标签唯一确定，样本是时间戳与数值。查询时先写选择器筛出序列集合，再用函数与运算符把序列变换或合并成想要的结果。理解瞬时向量与范围向量的区别，是用好这门语言的第一步。
四种结果类型
整个语言只有四类结果：瞬时向量（每个序列一个当前值）、范围向量（每个序列一段窗口内的样本）、标量（单个数值）与字符串（几乎不用）。图表与告警使用瞬时向量，函数参数使用范围向量，这就是最常见也最重要的两类用法。
基本信息
| 查询对象 | 时间序列：指标名加一组标签唯一确定 |
|---|---|
| 结果类型 | 瞬时向量、范围向量、标量、字符串 |
| 区间选择器 | 在瞬时向量后加 [时长]，只能作为函数参数 |
| 采样密度 | 由查询步长与抓取间隔共同决定 |
| 常用入口 | 表达式浏览器、HTTP 查询接口、看板查询框 |
典型使用场景
- 临时验证：确认某条序列是否存在、标签是否与预期一致
- 看板取数：把速率、分位、比率等表达式固化成面板查询
- 告警表达式：用瞬时向量与阈值比较，或做上下限判断
- 容量趋势：用范围函数观察一段时间内的均值与峰值
- 标签探索：通过查询结果反查真实存在的标签集合
- 数据核对：与原始计数器对比，验证速率类计算的口径
几种常见写法
| 写法 | 含义 | 适用场景 |
|---|---|---|
| http_requests_total | 瞬时向量，取所有序列的当前值 | 快速确认序列是否存在 |
| http_requests_total[5m] | 范围向量，只作为函数参数 | rate 等函数的输入 |
| rate(http_requests_total[5m]) | 每秒速率 | Counter 类指标的标准用法 |
| sum by (service) (rate(...)) | 按维度聚合成少数曲线 | 控制图表条数 |
两种向量的写法
两种向量的写法
http_requests_total # 瞬时向量：每条序列的当前值
http_requests_total[5m] # 范围向量：近 5 分钟的样本
http_requests_total{job="api"} # 标签精确过滤
http_requests_total{code=~"5.."} # 正则匹配（全串匹配）
sum by (job) (rate(http_requests_total[5m])) # 聚合成少数曲线选择器的常见坑
- 指标名拼错：返回空结果而不报错，先用自动补全确认名字
- 标签值大小写：prod 与 Prod 是两条不同序列，区分大小写
- 选择器过宽：没有标签限制会拉回全部序列，慢且看不清
- 窗口过短：范围向量窗口小于抓取间隔时取不到样本
区间选择器只能作为函数参数：在图表查询框里直接写范围向量会被拒绝，这是初学者最常遇到的报错。
选择器写错不会报错，只会得到空结果。排查顺序是先在表达式浏览器确认序列存在，再怀疑函数与聚合写法。
时区与时间范围
查询的时间范围由外部决定：表达式浏览器与看板各自控制起止时间，表达式本身只描述计算方式。理解这一点能避免两个常见误解——表达式里写死的窗口不会随看板缩放，看板上的曲线也不代表数据库里只存了这段时间。
调试表达式的顺序
- 先只写选择器，确认序列与标签符合预期
- 再套一层聚合，把曲线收敛到可读的数量
- 最后加函数与阈值，逐步逼近目标表达式
- 把验证过的表达式固化到看板或规则文件，避免每次重写
查询接口与看板用的是同一套表达式：在浏览器里验证通过后再固化，能避免在看板上反复试错。