Prometheus 标签重写与服务发现

中间件

Prometheus

本文档涵盖 Relabeling 标签重写机制（抓取前/抓取后两个阶段）以及多种服务发现方式（静态配置、文件、Kubernetes 等）。

符号说明

符号	含义
🚨	陷阱 / Pitfall
💡	最佳实践 / Best practice
🔬	深入原理 / Deep-dive
⚡	性能提示 / Performance note

1. Relabeling 标签重写

1.1 两个阶段

阶段	配置项	时机	操作对象
抓取前	`relabel_configs`	服务发现后、抓取前	目标标签（`__meta_*`、`__address__` 等）
抓取后	`metric_relabel_configs`	抓取后、存入 TSDB 前	所有指标及标签（含 `__name__`）

1.2 操作动作一览

Action	作用
`replace`	用正则替换标签值
`keep`	保留匹配的 targets/metrics
`drop`	丢弃匹配的 targets/metrics
`labelmap`	批量复制/重命名标签
`labeldrop`	删除匹配名称的标签
`labelkeep`	只保留匹配名称的标签
`hashmod`	哈希取模（多实例分片用）
`lowercase` / `uppercase`	转换标签值大小写

1.3 常用模式与示例

① 修改抓取地址（__address__）：

relabel_configs:
  - source_labels: [__address__]
    regex: '(.+):9100'
    replacement: '${1}:9090'
    target_label: __address__
    action: replace

② 只抓取特定命名空间的 Pod：

relabel_configs:
  - source_labels: [__meta_kubernetes_namespace]
    action: keep
    regex: 'production|staging'

③ 丢弃不需要的指标（节省存储空间）：

metric_relabel_configs:
  - source_labels: [__name__]
    action: drop
    regex: 'go_.*|process_.*'

④ 删除高基数标签（必须做！）：

metric_relabel_configs:
  - action: labeldrop
    regex: 'request_id|trace_id|span_id|pod_template_hash'

⑤ 批量映射 Kubernetes 标签：

relabel_configs:
  - action: labelmap
    regex: __meta_kubernetes_pod_label_(.+)
  # __meta_kubernetes_pod_label_app → app
  # __meta_kubernetes_pod_label_version → version

⑥ 重命名指标名称：

metric_relabel_configs:
  - source_labels: [__name__]
    regex: 'old_name'
    action: replace
    target_label: __name__
    replacement: 'new_name'

⑦ 多实例分片（hashmod）：

# Prometheus 实例 0 上
relabel_configs:
  - source_labels: [__address__]
    modulus: 3
    target_label: __tmp_hash
    action: hashmod
  - source_labels: [__tmp_hash]
    action: keep
    regex: '0'

💡 调试 relabeling 的最佳方式：在 Prometheus UI 的 Status → Service Discovery 和 Status → Targets 页面查看每一步的结果。

🚨 以 __ 开头的标签在 relabeling 完成后会被自动删除（除 __name__、__address__、__scheme__、__metrics_path__ 外）。

2. 服务发现

Prometheus 支持多种服务发现机制，用于动态发现抓取目标。

2.1 静态配置（static_configs）

最简单的方式，适用于固定 IP 的场景：

scrape_configs:
  - job_name: 'my-service'
    static_configs:
      - targets: ['10.0.0.1:8080', '10.0.0.2:8080']
        labels:
          env: 'production'

2.2 文件发现（file_sd_configs）

适用于配置管理工具或 CI/CD 动态更新目标列表：

scrape_configs:
  - job_name: 'file-sd'
    file_sd_configs:
      - files:
          - '/etc/prometheus/file_sd/*.json'
        refresh_interval: 5m

targets.json 文件格式：

[
  {
    "targets": ["host1:8080", "host2:8080"],
    "labels": {
      "env": "production",
      "team": "backend"
    }
  }
]

2.3 Kubernetes 服务发现

scrape_configs:
  - job_name: 'kubernetes-pods'
    kubernetes_sd_configs:
      - role: pod
        namespaces:
          names: ['production', 'staging']
    relabel_configs:
      # 仅抓取有 prometheus.io/scrape: "true" 注解的 Pod
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
        action: keep
        regex: 'true'
      # 自定义指标路径
      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
        action: replace
        target_label: __metrics_path__
        regex: '(.+)'
      # 自定义端口
      - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
        action: replace
        regex: '([^:]+)(?::\d+)?;(\d+)'
        replacement: '$1:$2'
        target_label: __address__
      # 映射命名空间和 Pod 名
      - source_labels: [__meta_kubernetes_namespace]
        target_label: namespace
      - source_labels: [__meta_kubernetes_pod_name]
        target_label: pod

2.4 其他服务发现

机制	配置项	适用场景
Consul	`consul_sd_configs`	Consul 注册中心
AWS EC2	`ec2_sd_configs`	AWS EC2 实例
DNS	`dns_sd_configs`	DNS A/AAAA/SRV 记录
GCE	`gce_sd_configs`	Google Compute Engine
Azure	`azure_sd_configs`	Azure 虚拟机
Docker	`docker_sd_configs`	Docker 容器
Marathon	`marathon_sd_configs`	Mesos/Marathon

参考资料：

Prometheus 配置文档 - relabel_config

Prometheus 服务发现

Prometheus 客户端埋点 (Instrumen...Prometheus 存储与扩展