WEEW12 BLOG

外观

（二）：核心配置详解 - 读懂prometheus.yml

约 3198 字大约 11 分钟

2026-03-28

导语

Prometheus 的所有核心能力（数据采集、规则计算、告警触发）均由 prometheus.yml 配置文件驱动。彻底理解该文件的结构与配置项，是掌握 Prometheus 实操的核心前提。本文将逐模块拆解配置文件的关键内容，结合实操示例讲透每个配置项的用法、场景与注意事项。

一、global 配置：全局参数

全局配置是 Prometheus 运行的基础，定义了所有子模块的默认行为（子模块可覆盖这些参数），核心作用是统一管控采集、规则评估的基础周期，以及全局标签。

1.1 核心参数详解（附示例）

global 块定义 Prometheus 全局默认规则，示例如下：

global:
  scrape_interval: 15s        # 全局默认采集间隔：每15秒拉取一次Target指标
  scrape_timeout: 10s         # 采集请求超时时间：超时未响应则放弃本次采集
  evaluation_interval: 30s    # 规则（Recording/Alerting Rule）评估周期
  # 外部标签：附加到所有时序数据（无冲突时），多用于多实例联邦部署
  external_labels:
    monitor: codelab
    foo: bar

1.2 关键参数注意事项

⚠️ 核心调优建议：

  • scrape_interval：默认 1 分钟，需按监控精度调整——核心服务（如支付）可缩短至 10s，非核心服务（如日志组件）可设为 1min，平衡精度与资源开销；
  • external_labels：不受 honor_labels 影响（后文详解），即使采集数据含同名标签，也仅“冲突时不添加”，而非覆盖；
  • evaluation_interval：规则评估越频繁，告警响应越及时，但会增加 Prometheus 计算负载；建议结合规则复杂度调整（如简单规则设为 15s，复杂聚合规则设为 1min）。

二、scrape_config：数据采集的核心配置

scrape_config 是 prometheus.yml 最核心的模块，决定 Prometheus 从何处、以何种规则拉取指标。每个 scrape_config 对应一个 job，可自定义采集周期、超时时间（覆盖全局），并支持多类 Target 发现方式。

2.1 基础配置（Job 级核心参数）

每个 Job 的基础配置用于定义采集规则，示例如下：

scrape_configs:
  - job_name: "prometheus"        # Job名称：会作为label附加到所有采集指标
    scrape_interval: 1m           # 覆盖全局采集间隔，仅对当前Job生效
    scrape_timeout: 5s            # 覆盖全局采集超时时间
    metrics_path: /metrics        # 采集指标的HTTP路径，默认/metrics
    scheme: http                  # 采集协议（http/https）
    params:                       # 采集请求携带的URL参数（如?test=test）
      test: ["test"]

2.2 static_configs：静态 Target 配置

适用于目标地址固定的场景（如本机 Prometheus、固定 IP 的中间件），可配置多 Target 并添加公共标签。

scrape_configs:
  - job_name: "static-targets"
    static_configs:
      - targets: ['localhost:9090', 'localhost:9191']  # 待采集目标列表
        labels:  # 公共标签：所有从这些Target采集的指标都会附加
          my: label
          your: label

适用场景：小规模、静态部署的服务（如物理机、单机固定端口应用）。

2.3 file_sd_configs：基于文件的服务发现

适用于 Target 动态更新的场景（无需重启 Prometheus），通过 JSON/YAML 文件管理 Target，Prometheus 定期检测文件变化并刷新。

scrape_configs:
  - job_name: "file-sd-targets"
    file_sd_configs:
      - files:  # 配置文件路径（支持通配符）
          - "foo/*.slow.json"
          - "foo/*.slow.yml"
          - "single/file.yml"
        refresh_interval: 10m  # 每隔10分钟刷新文件，更新Target列表

配套文件示例（single/file.yml）

- targets: ["192.168.1.100:8080", "192.168.1.101:8080"]
  labels:
    env: prod
    app: backend

适用场景：动态扩缩容的服务、跨环境 Target 管理（如测试/生产环境分开配置文件）。

2.4 其他主流服务发现方式

Prometheus 原生支持对接主流服务编排/注册组件，核心逻辑均为“动态获取 Target，无需修改 prometheus.yml”：

发现方式适用场景核心优势
KubernetesK8s 集群内服务监控自动发现 Pod/Service/Endpoint
Consul/ZooKeeper基于服务注册中心的微服务监控适配微服务动态扩缩容
云厂商适配（EC2/GCE/Azure）云服务器监控适配云资源弹性调度
DNS（SRV 记录）基于DNS解析的服务发现适配传统DNS服务架构

💡 提示：各类服务发现的详细配置可参考 Prometheus 官方文档，核心逻辑与文件发现一致。

2.5 honor_labels：标签冲突处理规则

当采集指标的标签与 Prometheus 默认附加标签（如 job、instance）冲突时，honor_labels 决定处理方式：

  • honor_labels: true：保留指标原有标签，忽略 Prometheus 附加的冲突标签；
  • honor_labels: false（默认）：在原有标签名前加 exported_ 前缀（如 job → exported_job），保留 Prometheus 标签。

配置示例：

scrape_configs:
  - job_name: "honor-labels-demo"
    honor_labels: true
    static_configs:
      - targets: ["localhost:8080"]

⚠️ 注意：global.external_labels 中的标签不受该配置影响。

2.6 relabel_configs：采集前的标签重写（核心灵活能力）

relabel_configs 是采集环节最灵活的配置，支持修改标签、过滤 Target、新增标签等操作，所有规则按配置顺序执行。

2.6.1 核心前置概念

Prometheus 执行 relabel 前，会为 Target 自动添加一批内部标签（以 __ 开头，不会持久化），核心如下：

  • __address__：Target 的 <host>:<port>；
  • __scheme__：采集协议（http/https）；
  • __metrics_path__：采集的 HTTP 路径；
  • __param_<name>：采集请求的 URL 参数；
  • __meta_*：服务发现附加的元数据（如 K8s 的 __meta_kubernetes_pod_name）。

2.6.2 常用操作示例（附注释）

scrape_configs:
  - job_name: "relabel-demo"
    static_configs:
      - targets: ["localhost:8080", "localhost:8081"]
    relabel_configs:
      # 示例1：替换标签值（默认action: replace）
      - source_labels: [__address__]
        regex: "(.*):8080"
        target_label: instance
        replacement: "web-$1"  # 8080端口的Target → instance=web-localhost
      
      # 示例2：过滤Target（action: drop）—— 丢弃8081端口的Target
      - source_labels: [__address__]
        regex: ".*:8081"
        action: drop
      
      # 示例3：保留Target（action: keep）—— 仅保留8080端口的Target
      - source_labels: [__address__]
        regex: ".*:8080"
        action: keep
      
      # 示例4：哈希取模（action: hashmod）—— 用于分片采集
      - source_labels: [__address__]
        modulus: 8
        target_label: __tmp_hash
      
      # 示例5：标签重命名（action: labelmap）—— k_xxx → k-xxx
      - action: labelmap
        regex: k_(.*)
        replacement: k-${1}
      
      # 示例6：删除标签（action: labeldrop）—— 删除名为"tmp"的标签
      - action: labeldrop
        regex: "tmp"

💡 技巧：临时标签建议以 __tmp_ 为前缀，避免与其他标签冲突。

三、Rule 配置：记录规则与告警规则

Prometheus 的 Rule 分为两类：

  • Recording Rule：预计算聚合指标，提升查询性能；
  • Alerting Rule：定义告警触发条件，触发后推送给 AlertManager。

两类规则均需通过 rule_files 指定配置文件路径。

3.1 规则文件加载配置

在 prometheus.yml 中指定规则文件路径（支持通配符）：

rule_files:
  - "first.rules"       # 单个规则文件
  - "my/*.rules"        # 通配符匹配多个文件

3.2 Recording Rule：预计算聚合指标

用于预先计算复杂 PromQL 结果（如多维度聚合、长时间窗口计算），将结果保存为新指标，避免重复计算。

配置示例：

groups:  # 规则组：按组执行，组内规则按顺序执行
  - name: "cpu-usage-rules"
    interval: 30s  # 覆盖全局evaluation_interval，仅对本组生效
    rules:
      - record: "node:cpu_usage:avg5m"  # 新指标名称（命名规范：层级:指标:聚合方式）
        expr: |
          sum without(cpu)(rate(node_cpu_seconds_total[5m])) / sum without(cpu)(count(node_cpu_seconds_total))
        labels:  # 附加到新指标的标签（冲突时覆盖）
          region: "cn-beijing"
          env: "prod"

适用场景：

  • 仪表盘常用聚合指标（如集群平均 CPU 使用率）；
  • 长时间窗口计算（如 1 小时流量总和）；
  • 多指标关联计算（如错误率 = 错误数 / 请求数）。

3.3 Alerting Rule：告警规则配置

定义告警触发条件、持续时间、附加信息，Prometheus 按 interval 评估规则，满足条件且持续指定时间后，向 AlertManager 发送告警。

配置示例：

groups:
  - name: "service-alerts"
    interval: 30s
    rules:
      - alert: "HighErrorRate"  # 告警名称（简洁描述问题）
        expr: |
          job:request_latency_seconds:mean5m{job="myjob"} > 0.5  # 告警触发条件
        for: 10m  # 告警等待期：避免瞬时抖动（如网络闪断）触发告警
        labels:  # 告警标签：用于AlertManager路由（如按级别分发）
          severity: "page"  # 告警级别：page（需立即处理）/warning（提醒）/info（通知）
          env: "prod"
        annotations:  # 告警描述：支持PromQL模板变量（人性化展示）
          summary: "高请求延迟（{{ $labels.job }}）"
          description: |
            服务{{ $labels.job }}的5分钟平均请求延迟超过0.5秒！
            实例：{{ $labels.instance }}
            当前值：{{ $value }}秒
            持续时间：{{ $for }}

关键参数说明：

  • for：核心防抖动参数，建议根据业务场景设置（如网络类告警设为 1-5min，业务类告警设为 5-10min）；
  • annotations：支持 $labels（标签值）、$value（指标值）、$for（持续时间）等模板变量；
  • labels.severity：建议标准化（page/warning/info），便于 AlertManager 按级别路由到不同渠道（如 page 级发钉钉/电话，info 级发邮件）。

四、AlertManager 配置：告警路由与分发

Prometheus 仅负责评估告警规则，实际的告警通知（邮件/钉钉/短信）由 AlertManager 完成。需在 prometheus.yml 中配置 AlertManager 地址与通信规则。

4.1 核心配置示例

alerting:
  alertmanagers:
    - scheme: https  # 与AlertManager通信的协议
      timeout: 10s   # 通信超时时间（补充原文档缺失项）
      relabel_configs:  # 发送告警前的标签重写（逻辑同采集环节）
        - source_labels: [__address__]
          regex: "(.*):9093"
          target_label: alertmanager_instance
          replacement: "am-$1"
      static_configs:  # 静态配置AlertManager地址（高可用部署）
        - targets:
            - "1.2.3.4:9093"
            - "1.2.3.5:9093"

4.2 动态发现 AlertManager

与采集 Target 类似，AlertManager 也支持文件发现（file_sd_configs）、K8s 发现等动态方式：

alerting:
  alertmanagers:
    - file_sd_configs:
        - files:
            - "alertmanagers/*.yml"
          refresh_interval: 5m  # 5分钟刷新一次配置文件

配套配置文件示例（alertmanagers/am.yml）

- targets: ["192.168.1.200:9093", "192.168.1.201:9093"]
  labels:
    dc: "dc1"  # 数据中心标签：便于按机房路由告警

五、远程存储配置：突破本地存储限制

Prometheus 本地 TSDB 受单机磁盘/性能限制，无法长期存储海量指标。通过 remote_write/remote_read 可对接远程存储，实现数据持久化、扩容、跨集群查询。

5.1 remote_write：指标写入远程存储

将采集的指标实时写入远程存储（如 Thanos、TimescaleDB、InfluxDB），配置示例：

remote_write:
  - url: "http://remote-storage:8086/api/v1/push"  # 远程存储写入地址
    # 写入前过滤/修改指标（如仅写入生产环境指标）
    relabel_configs:
      - source_labels: [env]
        regex: "prod"
        action: keep
    # 队列配置：避免网络异常导致数据丢失（补充原文档缺失的关键参数）
    queue_config:
      capacity: 10000        # 队列最大容量（默认10000）
      max_samples_per_send: 100  # 单次发送最大样本数
      batch_send_deadline: 5s    # 样本在队列中的最大等待时间
      max_retries: 3             # 写入失败后重试次数
      min_backoff: 30ms          # 重试最小间隔
      max_backoff: 100ms         # 重试最大间隔
      retry_on_http_429: true    # 429（限流）时是否重试（补充项）

5.2 remote_read：从远程存储读取指标

查询时优先从远程存储加载数据（补充本地存储的历史数据），配置示例：

remote_read:
  - url: "http://remote-storage:8086/api/v1/read"
    read_recent: true  # 优先读取近期数据（本地存储可能更全）
    timeout: 30s       # 读取超时时间
    # 仅读取指定指标（补充优化项）
    filter_relabel_configs:
      - source_labels: [__name__]
        regex: "node_cpu_.*|node_memory_.*"
        action: keep

5.3 常用远程存储方案对比

存储方案核心优势适用场景
Thanos开源、无限存储、跨集群查询大规模Prometheus集群
TimescaleDBPostgreSQL扩展，支持结构化+时序混合存储需关联业务数据的监控场景
InfluxDB专注时序数据，写入/查询性能优异高吞吐时序数据存储
M3DBUber开源分布式时序库，高可用超大规模集群（十万级指标）

六、配置实战小技巧

6.1 配置校验（必做！避免启动失败）

修改 prometheus.yml 后，先通过 Prometheus 自带工具校验：

promtool check config prometheus.yml

💡 提示：校验通过仅代表语法正确，需结合实际采集结果验证逻辑正确性。

6.2 热重载配置（无需重启，避免监控中断）

热重载需满足前提：启动 Prometheus 时指定 --web.enable-lifecycle 参数（开启生命周期 API）。

# 方式1：发送SIGHUP信号（推荐）
kill -HUP <prometheus_pid>

# 方式2：调用HTTP API
curl -X POST http://localhost:9090/-/reload

6.3 标签设计原则（性能+易用性双保障）

  1. 核心标签统一化：job/instance/env/region 保持全局一致，便于查询和聚合；
  2. 标签值轻量化：避免过长标签值（如完整URL、大段描述），影响存储和查询性能；
  3. 标签标准化：利用 relabel_configs 统一标签格式（如实例名、环境名）；
  4. 标签最小化：仅保留查询/聚合所需标签，避免冗余标签占用存储。

小结

本文完整拆解了 prometheus.yml 的核心配置模块：

  • 全局参数（global）：定义基础运行规则；
  • 采集配置（scrape_config）：管控指标拉取的来源、规则；
  • 规则配置（rule_files）：预计算指标、定义告警条件；
  • 告警分发（alerting）：对接 AlertManager 实现告警通知；
  • 远程存储（remote_write/read）：突破本地存储限制。

掌握这些配置，可灵活定制 Prometheus 采集策略——从单机服务监控到 K8s 集群动态采集，均可通过配置实现。

下一篇将深入 Prometheus 的“数据心脏”——TSDB，拆解其底层存储原理：数据分块、压缩、持久化逻辑，以及“近数据快、远数据慢”的核心原因。

Copyright © 2026 weew12