发布日期: 2026-08-18
版本号: v3.14.0

本次更新包含多项重要变更：弃用了/api/v1/query和/api/v1/query_range接口的stats参数非true/all的值；默认启用了PromQL时长表达式并提升了first_over_time至稳定。新增了Oracle云基础设施服务发现功能，以及实验性的start_timestamp函数和直方图起始时间戳支持。性能上优化了正则标签匹配器、远端读取和抓取解析。修复了包括告警管理器关闭时CPU占用、多种数据发现与抓取问题、PromQL正则匹配错误，以及TSDB中数据丢失、崩溃、查询阻塞和直方图数据不准确等多个关键缺陷。UI方面改进了语法高亮、添加了规则复制按钮并修正了状态页面的显示。

更新内容 （中文）

  • [变更] API：弃用 /api/v1/query 和 /api/v1/query_range 中 stats 查询参数的非 true 和 all 值。其他值仍启用基本统计信息，但现在会返回弃用警告；它们将在下一个主要版本中被拒绝。#19124
  • [变更] API：/api/v1/status/config 现在在重新标记配置中明确设置为空时，正确显示 separator: \"\" 和 replacement: \"\"，而不是省略它们。#18653
  • [变更] 发现/ Hetzner：按照 Hetzner Cloud API 中的移除，删除 hcloud 目标的 __meta_hetzner_datacenter 标签。#19269
  • [变更] PromQL：默认启用持续时间表达式。promql-duration-expr 功能标志现在为无操作。#19033
  • [变更] PromQL：将 first_over_time 提升至稳定状态。它不再需要 promql-experimental-functions 功能标志。#19093
  • [功能] 发现：添加 Oracle Cloud Infrastructure 计算服务发现 (oci_sd_configs)。#18919
  • [功能] PromQL：添加实验性 start_timestamp(instant-vector) 函数，返回给定向量中每个样本的起始时间戳。需要 use-start-timestamps 功能标志。#19089
  • [功能] PromQL：允许 rate() 和 increase() 使用起始时间戳作为速率外推的替代方案。隐藏在 use-start-timestamps 功能标志后。#18619
  • [功能] TSDB：添加对直方图和浮点直方图中编码起始时间戳的实验性支持。隐藏在 histograms-st-encoding 功能标志后。#18609
  • [增强] OTLP：当 OTLP 属性名称在清理后冲突到同一个 Prometheus 标签（例如，k8s.pod.name 和 k8s_pod_name 都变为 k8s_pod_name）时发出警告，并公开带有 category 标签的 prometheus_api_otlp_translation_warnings_total 计数器以跟踪此类警告。#18957
  • [增强] Promtool：在 push metrics 中添加 --remote-write.path 标志，用于使用非默认远程写入端点的后端。#19086
  • [增强] 远程写入：在远程写入 V2 协议中转发直方图起始时间戳。#18903
  • [增强] TSDB：添加 prometheus_tsdb_head_native_histogram_series 和 prometheus_tsdb_head_native_histogram_buckets 指标，用于跟踪头中的本机直方图系列和桶的数量。#19170
  • [增强] UI：为范围选择器和子查询中的 PromQL 持续时间表达式 (step()、range()、min_of()、max_of()) 添加语法高亮、自动补全和检查。#18625
  • [增强] UI：在规则和警报页面上为规则名称添加复制按钮。#18706
  • [增强] UI：改善规则页面上规则组标题的对比度。#19181
  • [性能] 加速正则表达式标签匹配器匹配一组字面值（例如 {job=~\"foo|bar|baz\"}）。#18833
  • [性能] 远程读取：通过移除不必要的每次写入刷新来提高远程读取吞吐量。#18470
  • [性能] Scrape：解析文本和 OpenMetrics 格式时不使用递归，防止深度嵌套或恶意公开输入导致的堆栈溢出。#19143
  • [性能] Scrape：将本机直方图抓取解析的分配减少约 49%。#19282
  • [性能] TSDB：加速对具有大量内存中块的系列的查询。#18300
  • [缺陷修复] 警报：修复关闭时可能导致优雅关闭延迟并触发基于超时的终止的 100% CPU 使用率问题。#17859
  • [缺陷修复] 发现/AWS：当 EC2、ECS、RDS、MSK、ElastiCache 和 Lightsail 服务发现配置中省略 region 字段时，停止 promtool check config 进行 AWS 元数据服务 (IMDS) 网络调用。#19037
  • [缺陷修复] 发现/Docker：为 unix、npipe 和 tcp 主机上的 docker_sd 和 dockerswarm_sd 设置请求超时。以前，无响应的守护程序可能会无限期冻结发现，将目标静默固定到过期的快照。#19237
  • [缺陷修复] 发现/Docker：修复 Docker Swarm 服务发现中当服务作为插件或网络附加运行时的恐慌。#19102
  • [缺陷修复] 发现/Docker：修复仅 IPv6 容器的发现。#18778
  • [缺陷修复] PromQL：修复不区分大小写的正则表达式标签匹配器静默丢弃匹配值的问题。#19167
  • [缺陷修复] PromQL：修复 mad_over_time 在范围包含 NaN 样本时返回 0 而不是 NaN 的问题。#19040
  • [缺陷修复] Promtool：在 check rules 中接受 --enable-feature=promql-binop-fill-modifiers，该功能以前会拒绝有效的 fill()/fill_left()/fill_right() 表达式。#19153
  • [缺陷修复] 远程写入：对于工作负载身份验证，遵循 AZURE_FEDERATED_TOKEN_FILE 环境变量，而不是硬编码令牌文件路径。#18973
  • [缺陷修复] 规则：当规则组在重新加载时被移除或重命名时，清理过时的 rule_group_last_rule_duration_sum_seconds 和 rule_group_last_restore_duration_seconds 系列。以前每次重新加载每个删除的组会泄漏两个系列，导致 /metrics 基数随时间增长。#19107
  • [缺陷修复] Scrape：修复 Scrape 管理器在关闭时以 100% CPU 运行的问题。#19149
  • [缺陷修复] TSDB：修复在配置文件中使用 stale_series_compaction_threshold 时可能导致的数据静默丢失和潜在崩溃循环。#19016
  • [缺陷修复] TSDB：修复启用乱序摄取并压缩块时重启可能导致的数据丢失。#19016
  • [缺陷修复] TSDB：修复 prometheus_tsdb_head_stale_series 在系列在浮点数、整数直方图和浮点直方图样本类型之间变化时过度计数和过早驱逐的问题。#19183
  • [缺陷修复] TSDB：修复 Prometheus 无法打开损坏 TSDB 时的 goroutine 和文件句柄泄漏。在 Windows 上，泄漏的目录句柄还阻止了 TSDB 目录删除。#18291
  • [缺陷修复] TSDB：修复乱序查询阻塞压缩数小时，导致内存使用量增长的问题。#19013
  • [缺陷修复] TSDB：修复已删除的系列在重启后导致样本缺失和错误的问题。#19140
  • [缺陷修复] TSDB：修复重启后本机直方图数据变得不正确的问题。#19202
  • [缺陷修复] TSDB：显示以前被静默丢弃的查询错误。#19120
  • [缺陷修复] TSDB：在压缩重写块时遵守配置的浮点块编码；以前使用 --enable-feature=xor2-encoding 编码的块在压缩后可能静默回退到 XOR。#19145
  • [缺陷修复] UI：当启用 --web.enable-admin-api 时，在 TSDB 状态页面上显示删除系列表单。#19025

更新内容 （原始）

  • [CHANGE] API: Deprecate the stats query parameter of /api/v1/query and /api/v1/query_range for values other than true and all. Other values still enable basic statistics but now return a deprecation warning; they will be rejected in the next major release. #19124
  • [CHANGE] API: /api/v1/status/config now correctly shows separator: "" and replacement: "" in relabel configs when explicitly set to empty, instead of omitting them. #18653
  • [CHANGE] Discovery/Hetzner: Drop the __meta_hetzner_datacenter label for hcloud targets, following its removal from the Hetzner Cloud API. #19269
  • [CHANGE] PromQL: Enable duration expressions by default. The promql-duration-expr feature flag is now a no-op. #19033
  • [CHANGE] PromQL: Promote first_over_time to stable. It no longer requires the promql-experimental-functions feature flag. #19093
  • [FEATURE] Discovery: Add Oracle Cloud Infrastructure compute service discovery (oci_sd_configs). #18919
  • [FEATURE] PromQL: Add experimental start_timestamp(instant-vector) function returning the start timestamp of each sample in the given vector. Requires the use-start-timestamps feature flag. #19089
  • [FEATURE] PromQL: Allow rate() and increase() to use start timestamps as an alternative for rate extrapolation. Hidden behind the use-start-timestamps feature flag. #18619
  • [FEATURE] TSDB: Add experimental support for encoding start timestamps in histograms and float histograms. Hidden behind the histograms-st-encoding feature flag. #18609
  • [ENHANCEMENT] OTLP: Emit a warning when OTLP attribute names collide into the same Prometheus label after sanitization (e.g. k8s.pod.name and k8s_pod_name both become k8s_pod_name), and expose the prometheus_api_otlp_translation_warnings_total counter labelled by category to track such warnings. #18957
  • [ENHANCEMENT] Promtool: Add --remote-write.path flag to push metrics for backends that use a non-default remote-write endpoint. #19086
  • [ENHANCEMENT] Remote write: Forward histogram start timestamps in the remote write V2 protocol. #18903
  • [ENHANCEMENT] TSDB: Add prometheus_tsdb_head_native_histogram_series and prometheus_tsdb_head_native_histogram_buckets gauges tracking the number of native histogram series and buckets in the head. #19170
  • [ENHANCEMENT] UI: Add syntax highlighting, autocompletion, and linting for PromQL duration expressions (step(), range(), min_of(), max_of()) in range selectors and subqueries. #18625
  • [ENHANCEMENT] UI: Add copy button next to rule names on the Rules and Alerts pages. #18706
  • [ENHANCEMENT] UI: Improve rule group title contrast on the Rules page. #19181
  • [PERF] Speed up regex label matchers matching a set of literal values (e.g. {job=~"foo|bar|baz"}). #18833
  • [PERF] Remote read: Improve remote read throughput by removing unnecessary per-write flushing. #18470
  • [PERF] Scrape: Parse text and OpenMetrics formats without recursion, preventing stack overflow from deeply nested or malicious exposition input. #19143
  • [PERF] Scrape: Reduce native histogram scrape parsing allocations by ~49%. #19282
  • [PERF] TSDB: Speed up queries on series with many in-memory chunks. #18300
  • [BUGFIX] Alerting: Fix 100% CPU usage on shutdown that could delay graceful shutdown and trigger timeout-based kills. #17859
  • [BUGFIX] Discovery/AWS: Stop promtool check config from making AWS metadata service (IMDS) network calls when the region field is omitted in EC2, ECS, RDS, MSK, ElastiCache, and Lightsail service discovery configs. #19037
  • [BUGFIX] Discovery/Docker: Set a request timeout for docker_sd and dockerswarm_sd on unix, npipe, and tcp hosts. Previously an unresponsive daemon could freeze discovery indefinitely, silently pinning targets to a stale snapshot. #19237
  • [BUGFIX] Discovery/Docker: Fix panic in Docker Swarm service discovery when a service runs as a plugin or network-attachment. #19102
  • [BUGFIX] Discovery/Docker: Fix discovery of IPv6-only containers. #18778
  • [BUGFIX] PromQL: Fix case-insensitive regex label matchers silently dropping matching values. #19167
  • [BUGFIX] PromQL: Fix mad_over_time returning 0 instead of NaN when the range contains a NaN sample. #19040
  • [BUGFIX] Promtool: Accept --enable-feature=promql-binop-fill-modifiers in check rules, which previously rejected valid fill()/fill_left()/fill_right() expressions. #19153
  • [BUGFIX] Remote write: Respect the AZURE_FEDERATED_TOKEN_FILE environment variable for workload identity authentication instead of hardcoding the token file path. #18973
  • [BUGFIX] Rules: Clean up stale rule_group_last_rule_duration_sum_seconds and rule_group_last_restore_duration_seconds series when a rule group is removed or renamed on reload. Previously each reload leaked two series per dropped group, growing /metrics cardinality over time. #19107
  • [BUGFIX] Scrape: Fix scrape manager spinning at 100% CPU on shutdown. #19149
  • [BUGFIX] TSDB: Fix silent data loss and potential crash loop when stale_series_compaction_threshold is used in the config file. #19016
  • [BUGFIX] TSDB: Fix potential data loss on restart when out-of-order ingestion is enabled and blocks are compacted. #19016
  • [BUGFIX] TSDB: Fix prometheus_tsdb_head_stale_series over-counting and early eviction of series that change between float, integer histogram, and float histogram sample types. #19183
  • [BUGFIX] TSDB: Fix goroutine and file handle leaks when Prometheus fails to open a corrupt TSDB. On Windows, the leaked directory handle also prevented TSDB directory removal. #18291
  • [BUGFIX] TSDB: Fix out-of-order queries blocking compaction for hours, causing memory usage to grow. #19013
  • [BUGFIX] TSDB: Fix deleted series causing missing samples and errors after restart. #19140
  • [BUGFIX] TSDB: Fix native histogram data becoming incorrect after restart. #19202
  • [BUGFIX] TSDB: Surface query errors that were previously silently discarded. #19120
  • [BUGFIX] TSDB: Honour the configured float chunk encoding when compaction rewrites chunks; previously chunks encoded with --enable-feature=xor2-encoding could silently revert to XOR after compaction. #19145
  • [BUGFIX] UI: Show the delete-series form on the TSDB Status page when --web.enable-admin-api is enabled. #19025

下载链接