Prometheus Relabeling 完全指南
区分抓取前的目标重标记、入库前的指标重标记及远程写入前的筛选。介绍 11 个 action、Kubernetes 注解和分片示例。
Relabeling 是 Prometheus 按处理阶段对标签进行增删改或筛选对象的机制:抓取前可以筛选目标、规范标签或分片,抓取后可以丢弃不必入库的指标样本。它是控制采集行为与基数的核心开关,也是公认的"配置两小时、报错一整天"的重灾区。这篇把它讲明白。
两个容易混淆的配置项
| 配置 | 作用时机 | 操作对象 |
|---|---|---|
relabel_configs |
抓取前 | 目标(target)的标签:决定抓谁、怎么改标签 |
metric_relabel_configs |
抓取后、入库前 | 指标(metric)的标签:决定存哪些指标 |
样本过滤不会省掉已发生的 HTTP 抓取或解析,也不影响 up 等自动生成的时序。只想限制某个 Remote Write 接收端收到的样本时,用 write_relabel_configs;发往 Alertmanager 的告警则用 alert_relabel_configs。两者都在外部标签处理之后执行。Prometheus 配置说明(英文)
内部标签:以 __ 开头的隐藏维度
服务发现会给每个目标生成一批 __ 前缀的内部标签,relabeling 的主要原料:
__address__:目标地址(如10.0.0.5:9100)__scheme__、__metrics_path__:协议与指标路径__meta_kubernetes_pod_name、__meta_kubernetes_namespace……:K8s 服务发现注入的元信息__name__:指标名,可在样本阶段使用,如metric_relabel_configs和write_relabel_configs。
目标规则按顺序执行。结束后移除发现元数据,抓取地址等 __ 开头的内部字段不会出现在公开目标标签中。临时结果可用 __tmp 前缀。若未设置 instance,则用最终的 __address__。需要查询发现元数据时,先把相关值复制到普通标签。
配置结构逐个拆解
relabel_configs:
- source_labels: [__meta_kubernetes_namespace]
separator: ';'
regex: '(production|staging)'
replacement: '$1'
target_label: env
action: replace
源标签不存在时按空字符串处理,多标签默认用分号连接。RE2 正则默认匹配整个输入。上例只在命名空间完全匹配时给目标设置 env,不筛掉其他目标。用 keep 可以筛选目标,但它不会写入标签。默认 action 是 replace,默认正则是 (.*),默认替换值是 $1。
十一个 action 逐个讲
keep / drop:目标筛选
- source_labels: [__meta_kubernetes_namespace]
regex: 'production'
action: keep
keep = 不匹配就丢弃;drop = 匹配就丢弃。
replace:改写标签值
- source_labels: [__meta_kubernetes_pod_name]
target_label: pod
regex: '(.*)'
replacement: '$1'
action: replace
labelkeep / labeldrop:按名字整批处理标签
- regex: 'build_sha|request_id'
action: labeldrop
这些动作匹配标签名。删掉区分不同序列的标签,可能让指标名和剩余标签完全相同,无法继续区分。
labelmap:批量复制到新标签名
- regex: '__meta_kubernetes_pod_label_(app|team)'
replacement: '$1'
action: labelmap
原标签在这一步仍然保留。目标阶段结束后,内部发现标签会被移除,这里只保留需要查询的 app 和 team。规则过宽可能引入高基数维度,或者覆盖已有的同名标签。
hashmod:分片(水平扩容)
- source_labels: [__address__]
modulus: 2
target_label: __tmp_hash
action: hashmod
- source_labels: [__tmp_hash]
regex: '0'
action: keep
另一分片应对相同的候选目标、同一哈希输入和模数保留余数 1。不同余数可分摊抓取,数量不保证均分;配置相同的副本会抓同一组目标。
keepequal / dropequal、uppercase / lowercase
keepequal 和 dropequal 用 source_labels 拼接值与 target_label 的当前值做精确比较,相等时分别保留或丢弃。uppercase 和 lowercase 转换拼接值的大小写并写入目标标签。
实战配方
K8s 里只抓带注解的 Pod:放在使用 Kubernetes Pod 服务发现的抓取任务中。端口注解缺失或地址格式未匹配时,第二条规则保留原地址。示例支持主机名、IPv4 和带方括号的 IPv6。
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
regex: 'true'
action: keep
- source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_port, __address__]
regex: '([0-9]+);(\[[^]]+\]|[^:]+)(:[0-9]+)?'
replacement: '${2}:${1}'
target_label: __address__
丢弃确认不需要入库的指标:先确认告警和仪表盘的依赖。示例按指标名精确排除 http_request_debug_total。
metric_relabel_configs:
- source_labels: [__name__]
regex: 'http_request_debug_total'
action: drop
调试方法
- Prometheus UI 的 Service Discovery 和 Targets 页面可核对发现标签、目标是否被保留及抓取状态;
- 重新加载前检查配置,再查询保留和被过滤的指标。第二条命令执行指定任务的服务发现,需要能访问发现来源,任务名按实际配置替换。promtool 命令参考(英文)
promtool check config prometheus.yml
promtool check service-discovery prometheus.yml kubernetes-pods
常见问题(FAQ)
Q:改完 relabel_configs 没生效?
A:三查:配置真的 reload 了吗(发 SIGHUP,或启用生命周期 API 后向 /-/reload 发 HTTP POST)?Service Discovery 页面里目标标签变了吗?你的正则有没有按默认规则匹配整个输入?
Q:正则里的 $1 没被替换?
A:正则中要有对应的捕获组,replacement 才能用 $1 引用它。组号后紧接其他字符时可用 ${1},输出字面量 $ 则写 $$。
Q:relabel 会影响历史数据吗?
A:不会。已入库的序列保持原样,后续抓取可能以新的标签组合产生新序列——这也是标签治理要趁早的原因。