可观测性与稳定性 / 知识点

PromQL 查询速查手册

基础查询

CODE
up{job="prometheus"}

使用标签匹配器缩小指标查询范围,适合按 job、instance、环境或业务维度定位时间序列;注意正则和否定匹配可能扩大扫描范围。

按标签筛选时间序列

当一个指标包含大量实例、环境或业务标签时,用标签匹配器把查询限定到目标时间序列。最常用的是精确匹配 =,需要集合或模式时再使用 =~;否定匹配要特别留意“标签不存在”也可能被选中。

基本语法

即时向量选择器由指标名和一组标签匹配器组成:

promql
up{job="prometheus"}

预期输出

text
up{instance="localhost:<PORT>", job="prometheus"} 1

在 Prometheus 表达式浏览器的 Table 视图中,每一行代表一条匹配到的时间序列及其当前样本值。<PORT> 等实际标签值会因部署而不同;这里的 up 值为 1 表示该目标最近一次抓取成功。

常用匹配器

匹配器 含义 示例
= 标签值完全相等 job="prometheus"
!= 标签值不等于指定值 environment!="prod"
=~ 标签值匹配正则表达式 `job=~"prometheus
!~ 标签值不匹配正则表达式 instance!~"test-.*"

正则匹配使用 RE2 语法,并按完整标签值匹配;例如 job=~"api|web" 匹配值为 api 或 web 的标签,而不是任意包含这两个片段的字符串。多个匹配器写在同一对花括号内时是 AND 关系,必须全部满足。

高频用法

按单个维度定位时优先精确匹配,例如 http_requests_total{job="api"}。需要同时覆盖多个已知值时,可用 job=~"api|worker",避免写多条查询再手工合并。

排除已知环境时可以写 metric{environment!="test"},但这也会匹配没有 environment 标签的时间序列,因为缺失标签按空字符串参与匹配。若必须保证标签存在,可增加一个不能匹配空字符串的正则条件,例如 environment=~".+"。

只写标签选择器而省略指标名也是允许的,但至少要有一个不能匹配空字符串的匹配器。例如 {job=~".+"} 合法,而 {job=~".*"} 会被拒绝,因为后者允许空值,可能退化为过宽的选择器。

风险与边界

避免把业务自由文本、请求 ID 等高基数字段直接当标签后再依赖正则检索;这类设计会先制造大量时间序列,再把成本转移到查询阶段。更安全的做法是保留稳定、低基数的维度标签,把明细检索交给日志或追踪系统。

排障清单

查询返回为空时,先去掉部分匹配器确认指标本身是否存在,再检查标签名和标签值是否拼错。正则结果异常时,确认表达式按完整标签值匹配,并检查是否误把 shell 或 PCRE 的写法带入 RE2。

查询返回“比预期更多”的序列时,重点检查 != 与 !~:如果某些序列根本没有该标签,它们仍可能满足否定条件。先用 label=~".+" 验证标签存在性,再叠加其他条件,通常能快速定位问题。

常用操作

进阶查询

排障

目录与阅读设置

记录一个想法

PromQL 查询速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通