Prometheus 3.0 迁移指南

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

标志

  • 以下特性标志已被删除，并且已添加到 Prometheus v3 的默认行为中
    • promql-at-modifier
    • promql-negative-offset
    • remote-write-receiver
    • new-service-discovery-manager
    • expand-external-labels
      • 外部标签值中的环境变量引用 ${var} 或 $var 将根据当前环境变量的值进行替换。
      • 对未定义变量的引用将被空字符串替换。可以使用 $$ 转义 $ 字符。
    • no-default-scrape-port
      • Prometheus v3 将不再根据指定的方案向抓取目标添加端口。目标现在将按配置出现在标签中。
      • 如果您依赖像 https://example.com/metrics 或 http://exmaple.com/metrics 这样的抓取目标分别表示为 https://example.com/metrics:443 和 http://example.com/metrics:80，请将其添加到您的目标 URL 中
    • agent
      • 请改为使用专用的 --agent 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。为了在多个套接字上并行化多个远程写入队列，最好不要默认使用 http2。如果您希望为远程写入使用 http2，您现在必须在 remote_write 配置部分中设置 http_config.enable_http2: true。

PromQL

  • PromQL 中正则表达式中的 . 模式匹配换行符。通过此更改，像 .* 这样的正则表达式匹配包含 \n 的字符串。这适用于查询和重新标记配置中的匹配器。
    • 例如，以下正则表达式现在匹配随附的字符串，而在 Prometheus v2 中，这些组合不匹配。
      • .* 另外匹配 foo\n 和 Foo\nBar
      • foo.?bar 另外匹配 foo\nbar
      • foo.+bar 另外匹配 foo\nbar
    • 如果您希望 Prometheus v3 的行为类似于 v2，则必须通过将所有 . 模式替换为 [^\n] 来更改正则表达式，例如 foo[^\n]*。
  • 回溯和范围选择器是左开右闭的（以前是左闭右闭的）。当评估时间与样本时间戳完全对齐时，此更改会影响查询。例如，假设查询一个时间序列，其中均匀分布的样本间隔正好为 1 分钟。在 Prometheus v3 之前，带有 5m 的范围查询通常会返回 5 个样本。但是，如果查询评估与抓取完美对齐，则它将返回 6 个样本。在 Prometheus v3 中，这样的查询将始终返回 5 个样本。
    除了某些子查询用例外，此更改可能对日常使用几乎没有影响。
    对齐查询的查询前端通常将子查询对齐到步长的倍数。这些子查询可能会受到影响。
    测试更有可能受到影响。要修复这些问题，请调整预期样本数或将范围延长小于一个样本间隔。
  • 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 或文本格式）。这导致标签值根据抓取协议而改变。例如，一个以 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 文档。

此文档是 开源的。请通过提交问题或拉取请求来帮助改进它。