Prometheus 3.x 配置参数详解

目标：详解 Prometheus 3.15.0（实测）的配置文件（prometheus.yml）核心段与运行时参数，并实测确认 3.x 与 2.x 的关键差异（PromQL 变化、UTF-8 指标名、配置文件/CLI 变化、promtool 子命令变化）。所有输出均来自 Prometheus 3.15.0 二进制真实实测。

环境信息

配置文件（prometheus.yml）核心段

Prometheus 配置文件为 YAML 格式，由 --config.file 指定。3.15.0 自带默认配置实测如下：

# my global config
global:
  scrape_interval: 15s          # 抓取间隔：每 15 秒抓取一次目标（默认 1m）
  evaluation_interval: 15s      # 规则评估间隔：每 15 秒评估一次规则（默认 1m）
  # scrape_timeout: 10s         # 单次抓取超时（默认 10s，不能大于 scrape_interval）

# Alertmanager configuration
alerting:
  alertmanagers:
    - static_configs:
        - targets:
          # - alertmanager:9093

# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
rule_files:
  # - "first_rules.yml"
  # - "second_rules.yml"

scrape_configs:
  - job_name: "prometheus"
    static_configs:
      - targets: ["localhost:9090"]
        labels:
          app: "prometheus"
    scrape_native_histograms: true   # 3.x 默认配置新增（2.x 无此行）

段 1：global（全局配置）

段 2：scrape_configs（抓取配置）

每个抓取任务为一个 job，核心子参数（实测默认配置 + promtool 校验）：

💡 说明：targets 支持静态列表，也可用服务发现（file_sd、consul_sd、kubernetes_sd 等）动态生成。

段 3：rule_files（规则文件）

rule_files:
  - "alerts.yml"          # 支持通配符，如 /etc/prometheus/rules/*.yml

规则文件内可定义记录规则（recording rule）与告警规则（alerting rule）。实测：

promtool check config /etc/prometheus/prometheus.yml

实测输出：

Checking /etc/prometheus/prometheus.yml
  SUCCESS: 1 rule files found
 SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax

Checking /etc/prometheus/alerts.yml
  SUCCESS: 2 rules found

段 4：alerting（告警配置）

alerting:
  alertmanagers:
    - static_configs:
        - targets: []
          # - "alertmanager:9093"

💡 说明：配置 Alertmanager 地址列表，Prometheus 将触发告警推送过去。不配告警则留空。3.x 起 Alertmanager 仅支持 v2 API（实测 release notes 确认：Disallow configuring AM with the v1 api）。

段 5：otlp（3.x 新增，OTLP 接收配置）

otlp:
  translation_strategy: NoUTF8EscapingWithSuffixes

💡 说明：配合 --web.enable-otlp-receiver 使用。默认对 OTLP 指标名做规范化（UTF-8 转 ASCII），实测中文指标名默认推送报 HTTP 500 normalization for metric "温度计" resulted in empty name；配置 NoUTF8EscapingWithSuffixes 后保留 UTF-8 名称（实测配置后配置校验通过）。

运行时参数（命令行 flag）

用 ./prometheus --help 实测。以下为运维最常用的参数：

实测 --enable-feature 完整选项（./prometheus --help）：

Valid options: concurrent-rule-eval, created-timestamp-zero-ingestion,
delayed-compaction, exemplar-storage, extra-scrape-metrics,
histograms-st-encoding, memory-snapshot-on-shutdown, metadata-wal-records,
old-ui, openmetrics2, otlp-deltatocumulative, otlp-native-delta-ingestion,
promql-binop-fill-modifiers, promql-delayed-name-removal,
promql-experimental-functions, promql-extended-range-selectors,
promql-per-step-stats, search-api, st-storage, st-synthesis,
type-and-unit-labels, use-start-timestamps, use-uncached-io, xor2-encoding,
zstd-scrape

💡 说明：其中 old-ui 可切回 2.x 老 UI；promql-experimental-functions 开启实验性 PromQL 函数；auto-reload-config（3.0 新增）支持配置自动重载（release notes 确认）。

热加载配置实测（--web.enable-lifecycle）

# 未开启 flag：实测返回 403
curl -s -X POST http://localhost:9090/-/reload -o /dev/null -w "%{http_code}"
# 开启 flag 后：实测返回 200
curl -s -X POST http://localhost:9090/-/reload -o /dev/null -w "%{http_code}"

实测输出：

403
200

admin API 实测（--web.enable-admin-api）

curl -s -X POST http://localhost:9090/api/v1/admin/tsdb/snapshot

未开 flag 实测输出：

{"status":"error","errorType":"unavailable","error":"admin APIs disabled"}

开启 flag 后实测输出：

{"status":"success","data":{"name":"20260926T213128Z-5e7a03741436bdd5"}}

3.x 与 2.x 的关键差异（实测确认）

PromQL 变化实测

查询 UTF-8 指标名（3.x 新语法，实测）：

curl -s --get "http://localhost:9090/api/v1/query" --data-urlencode 'query={"温度计"}'

💡 说明：2.x 指标名必须符合 [a-zA-Z_:][a-zA-Z0-9_:]*；3.x 支持 UTF-8 名称，查询时名称需加引号并放入大括号：{"温度计"}，标签同理 {"metric.name", "label"=...}。

注意事项

• --web.enable-lifecycle 与 --web.enable-admin-api 默认关闭（实测 403 / admin APIs disabled），生产按需开启；admin API 无鉴权，勿暴露公网
• scrape_timeout 不能大于 scrape_interval，否则抓取会重叠
• --storage.tsdb.retention.time 与 .size 同时设置时先达者生效
• 3.x 移除的 flag 直接使用会启动报错，升级 2.x→3.x 前先 promtool check config 校验并阅读迁移指南
• UTF-8 指标名：抓取 text 格式实测不支持（expected metric name after HELP），接入 OTLP 并配置 otlp.translation_strategy: NoUTF8EscapingWithSuffixes 才可保留中文名

常见问题

问题 1：启动报 unknown flag / 2.x 参数在 3.x 失效

原因： 3.x 移除了一批 2.x 参数（--storage.tsdb.retention、--alertmanager.timeout、--enable-feature=agent 等，实测 --help 已无）。

解决： 用 prometheus --help 核对新参数：retention 改 --storage.tsdb.retention.time；agent 用 --agent；OTLP 用 --web.enable-otlp-receiver。

问题 2：修改 prometheus.yml 后不生效

原因： 未开 --web.enable-lifecycle 时 /-/reload 返回 403（实测）。

解决： 启动加 --web.enable-lifecycle，改完配置执行 curl -X POST http://localhost:9090/-/reload（实测返回 200）；或用 kill -HUP <pid>。

问题 3：抓取含中文指标名目标一直 down

原因： 实测 Prometheus 3.15 text/OpenMetrics 抓取报 expected metric name after HELP, got "\xe6" ("INVALID")，抓取失败——UTF-8 支持默认启用但抓取解析路径仍按 legacy 校验。

解决： 抓取目标用 ASCII 指标名；需 UTF-8 名称时走 OTLP（--web.enable-otlp-receiver + otlp.translation_strategy: NoUTF8EscapingWithSuffixes）。

问题 4：promtool tsdb ls 报 expected command but got "ls"

原因： 3.x 重命名了 tsdb 子命令（实测报错）。

解决： 用 promtool tsdb list / tsdb dump；快照功能改走 admin API POST /api/v1/admin/tsdb/snapshot（需 --web.enable-admin-api）。

参考链接

• 官方配置文档：https://prometheus.io/docs/prometheus/latest/configuration/configuration/
• Feature flags：https://prometheus.io/docs/prometheus/latest/feature_flags/
• 3.0 迁移指南：https://prometheus.io/docs/prometheus/3.0/migration/
• UTF-8 指南：https://next.prometheus.io/docs/guides/utf8/
• 3.0.0 Release Notes：https://github.com/prometheus/prometheus/releases/tag/v3.0.0

本文档由 www.quzuo.net 平台开发