Prometheus 3.0 迁移指南

根据我们的稳定性承诺，Prometheus 3.0 版本包含一些向后不兼容的更改。本文档提供了从 Prometheus 2.x 迁移到 Prometheus 3.0 及更新版本的指南。

标志

  • 以下功能标志已被移除，并已添加到 Prometheus v3 的默认行为中
    • promql-at-modifier
    • promql-negative-offset
    • new-service-discovery-manager
    • expand-external-labels
      • 外部标签值中对环境变量的引用 ${var} 或 $var 将根据当前环境变量的值进行替换。
      • 对未定义变量的引用将被替换为空字符串。可以使用 $$ 来转义 $ 字符。
    • no-default-scrape-port
      • Prometheus v3 将不再根据指定的 scheme 为抓取目标添加端口。现在目标将按照配置显示在标签中。
      • 如果您依赖于像 https://example.com/metrics 或 http://example.com/metrics 这样的抓取目标分别表示为 https://example.com/metrics:443 和 http://example.com/metrics:80，请将它们添加到您的目标 URL 中
    • agent
      • 请改用专用的 --agent CLI 标志。
    • remote-write-receiver
      • 请改用专用的 --web.enable-remote-write-receiver CLI 标志来启用远程写入接收器。
    • auto-gomemlimit
      • Prometheus v3 将自动设置 GOMEMLIMIT 以匹配 Linux 容器内存限制。如果不存在容器限制，或者进程在容器外运行，则使用系统内存总量。要禁用此功能，可以使用 --no-auto-gomemlimit。
    • auto-gomaxprocs
      • Prometheus v3 将自动设置 GOMAXPROCS 以匹配 Linux 容器 CPU 配额。要禁用此功能，可以使用 --no-auto-gomaxprocs。

如果您继续将这些标志传递给 --enable-feature，Prometheus v3 将记录警告。

配置

  • 抓取作业级别的配置选项 scrape_classic_histograms 已重命名为 always_scrape_classic_histograms。如果您使用 --enable-feature=native-histograms 功能标志来接收原生直方图，并且还想接收端点可能与原生直方图一起暴露的经典直方图，请务必添加此配置或将配置从旧名称更改过来。
  • remote_write 项中的 http_config.enable_http2 默认值已更改为 false。在 Prometheus v2 中，远程写入 http 客户端默认使用 http2。为了并行化多个远程写入队列 across 多个 socket，最好不要默认使用 http2。如果您希望在远程写入时使用 http2，现在必须在 remote_write 配置部分中设置 http_config.enable_http2: true。

PromQL

正则表达式匹配换行符

PromQL 中正则表达式的 . 模式现在匹配换行符。通过此更改，像 .* 这样的正则表达式将匹配包含 \n 的字符串。这适用于查询中的匹配器和 relabel 配置。

例如，以下正则表达式现在匹配相应的字符串，而在 Prometheus v2 中这些组合不匹配。- .* 额外匹配 foo\n 和 Foo\nBar - foo.?bar 额外匹配 foo\nbar - foo.+bar 额外匹配 foo\nbar

如果您希望 Prometheus v3 的行为与 v2 类似，您必须通过将所有 . 模式替换为 [^\n] 来更改您的正则表达式，例如 foo[^\n]*。

范围选择器和回顾（lookback）排除与左边界重合的样本

回顾（lookback）和范围选择器现在是左开右闭（以前是左闭右闭），这使得它们的行为更加一致。此更改影响查询中范围的左边界或回顾 delta 与一个或多个样本的时间戳重合的情况。

例如，假设我们正在查询一个时间序列，其样本间隔恰好为 1 分钟。在 Prometheus v3 之前，带有 5m 的范围查询通常会返回 5 个样本。但如果查询评估与抓取完全对齐，它会返回 6 个样本。在 Prometheus v3 中，像这样的查询在样本间隔均匀的情况下将始终返回 5 个样本。

此更改通常会影响子查询，因为它们的评估时间自然是完全均匀间隔的，并且与子查询分辨率的倍数时间戳对齐。此外，查询前端通常会将子查询对齐到步长的倍数。结合起来，这很容易造成完全相互对齐的情况，这通常是用户无意或不知道的，因此新行为可能会令人意外。在 Prometheus V3 之前，在此类系统上对 foo[1m:1m] 进行子查询可能总是返回两个点，从而允许进行速率计算。然而，在 Prometheus V3 中，此类子查询只会返回一个点，这不足以进行速率或增加计算，从而导致返回 No Data。

此类查询需要重写以延长窗口，以便正确覆盖一个以上的点。在此示例中，无论查询对齐如何，foo[2m:1m] 将始终返回两个点。重写查询的确切形式可能取决于预期的结果，并且对于行为已更改的查询没有通用的直接替代方案。

测试也更容易受到影响。要解决这些问题，请调整预期的样本数量或延长范围。

holt_winters 函数已重命名

holt_winters 函数已重命名为 double_exponential_smoothing，现在受 promql-experimental-functions 功能标志的保护。如果您想继续使用 holt_winters，您必须同时执行以下两项操作：- 在您的查询中将 holt_winters 重命名为 double_exponential_smoothing。- 在您的 Prometheus CLI 调用中传递 --enable-feature=promql-experimental-functions。

抓取协议

Prometheus v3 对抓取时接收到的 Content-Type 头部更加严格。如果在抓取目标未指定 Content-Type 头部，或者头部无法解析或无法识别，Prometheus v2 会默认使用标准的 Prometheus 文本协议。这可能导致抓取中解析的数据不正确。Prometheus v3 在此类情况下将使抓取失败。

如果抓取目标未提供正确的 Content-Type 头部，可以使用 fallback_scrape_protocol 参数指定回退协议。请参阅Prometheus scrape_config 文档。

这是一项破坏性更改，因为在 Prometheus v2 中可能成功的抓取如果未指定此回退协议现在可能会失败。

杂项

TSDB 格式和降级

TSDB 格式在 Prometheus v2.55 中略有改动，为索引格式的更改做准备。因此，Prometheus v3 TSDB 只能由 Prometheus v2.55 或更新版本读取。在升级到 v3 时请记住这一点——您只能降级到 v2.55，不能更低，否则会丢失您的 TSDB 持久数据。

作为额外的安全措施，您可以选择先升级到 v2.55 并确认 Prometheus 按预期工作，然后再升级到 v3。

TSDB 存储契约

现在，与 TSDB 兼容的存储期望返回与指定选择器匹配的结果。这可能会影响一些第三方实现，最可能是实现 remote_read 的那些。

此契约未强制执行，但可能导致未定义行为。

UTF-8 名称

Prometheus v3 支持在指标和标签名称中使用 UTF-8。这意味着升级后指标和标签名称可能会根据端点暴露的内容而改变。此外，以前被标记为无效的指标和标签名称将不再如此。

希望保留原始验证行为的用户可以更新其 Prometheus yaml 配置以指定旧版验证方案

global:
  metric_name_validation_scheme: legacy

或按抓取任务指定

scrape_configs:
  - job_name: job1
    metric_name_validation_scheme: utf8
  - job_name: job2
    metric_name_validation_scheme: legacy

日志消息格式

Prometheus v3 已采用 log/slog 取代之前的 go-kit/log。这导致日志消息格式发生变化。旧日志格式的示例如下

ts=2024-10-23T22:01:06.074Z caller=main.go:627 level=info msg="No time or size retention was set so using the default time retention" duration=15d
ts=2024-10-23T22:01:06.074Z caller=main.go:671 level=info msg="Starting Prometheus Server" mode=server version="(version=, branch=, revision=91d80252c3e528728b0f88d254dd720f6be07cb8-modified)"
ts=2024-10-23T22:01:06.074Z caller=main.go:676 level=info build_context="(go=go1.23.0, platform=linux/amd64, user=, date=, tags=unknown)"
ts=2024-10-23T22:01:06.074Z caller=main.go:677 level=info host_details="(Linux 5.15.0-124-generic #134-Ubuntu SMP Fri Sep 27 20:20:17 UTC 2024 x86_64 gigafips (none))"

新日志格式中类似的序列如下所示

time=2024-10-24T00:03:07.542+02:00 level=INFO source=/home/user/go/src/github.com/prometheus/prometheus/cmd/prometheus/main.go:640 msg="No time or size retention was set so using the default time retention" duration=15d
time=2024-10-24T00:03:07.542+02:00 level=INFO source=/home/user/go/src/github.com/prometheus/prometheus/cmd/prometheus/main.go:681 msg="Starting Prometheus Server" mode=server version="(version=, branch=, revision=7c7116fea8343795cae6da42960cacd0207a2af8)"
time=2024-10-24T00:03:07.542+02:00 level=INFO source=/home/user/go/src/github.com/prometheus/prometheus/cmd/prometheus/main.go:686 msg="operational information" build_context="(go=go1.23.0, platform=linux/amd64, user=, date=, tags=unknown)" host_details="(Linux 5.15.0-124-generic #134-Ubuntu SMP Fri Sep 27 20:20:17 UTC 2024 x86_64 gigafips (none))" fd_limits="(soft=1048576, hard=1048576)" vm_limits="(soft=unlimited, hard=unlimited)"

le 和 quantile 标签值

在 Prometheus v3 中，经典直方图的 le 标签值和摘要的 quantile 标签值在接收时会被规范化。在 Prometheus v2 中，这些标签的值在某些情况下取决于抓取协议（protobuf vs 文本格式）。这导致标签值随抓取协议的变化而变化。例如，以 my_classic_hist{le="1"} 暴露的指标通过文本格式接收时仍为 my_classic_hist{le="1"}，但通过 protobuf 接收时则为 my_classic_hist{le="1.0"}。这改变了指标的身份，并在查询指标时引起问题。在 Prometheus v3 中，这些标签值将始终规范化为浮点表示形式。也就是说，上面的示例将始终导致 my_classic_hist{le="1.0"} 被接收到 prometheus 中，无论通过哪种协议。此更改的影响是，直接引用整数标签值（例如 le="1"）的告警、记录规则和仪表盘将停止工作。

处理此更改的方法（全局或按指标）

  • 修复对整数 le、quantile 标签值的引用，但不进行其他操作，并接受某些跨越过渡时间的查询会产生不准确或意外的结果。这是推荐的解决方案。
  • 在抓取目标时使用 metric_relabel_config 来保留旧标签。这应该仅应用于当前产生此类标签的指标。
    metric_relabel_configs:
      - source_labels:
          - quantile
        target_label: quantile
        regex: (\d+)\.0+
      - source_labels:
          - le
          - __name__
        target_label: le
        regex: (\d+)\.0+;.*_bucket

禁止使用 v1 API 配置 Alertmanager

Prometheus 3 不再支持 Alertmanager 的 v1 API。实际上，Prometheus 3 需要 Alertmanager 0.16.0 或更高版本。使用旧版本 Alertmanager 或使用 alerting: alertmanagers: [api_version: v1] 配置的用户需要升级 Alertmanager 并将其配置更改为使用 api_version: v2。

Prometheus 2.0 迁移指南

有关从 Prometheus 1.8 迁移到 2.0 的指南，请参阅 Prometheus v2.55 文档。

本文档是开源的。请通过提交 issue 或 pull request 帮助改进它。