发布日期: 2026-08-11
版本号: v3.14.0-rc.0

API方面：废弃了查询接口中stats参数对非true和all值的支持，当前其他值仍返回基本统计但会发出警告，未来版本将彻底拒绝；/api/v1/status/config接口现在能正确显示重标签配置中明确设置为空字符串的separator和replacement字段。发现组件方面：移除了Hetzner云目标的__meta_hetzner_datacenter标签。PromQL方面：默认启用时间间隔表达式，first_over_time函数升级为稳定版；新增了实验性的start_timestamp函数，并允许rate()和increase()使用起始时间戳进行外推，这些新功能需通过特定功能标志启用。新功能还包括增加了Oracle云基础设施计算服务发现。性能优化涵盖：提升正则标签匹配速度、改进远程读取吞吐量、优化文本格式解析以避免栈溢出、减少原生直方图抓取解析的内存分配，并加速包含大量内存块的序列查询。错误修复部分解决了多项问题：包括关闭时CPU占用过高、发现服务无响应导致冻结、PromQL正则匹配错误、直方图重启后数据不准确、序列查询阻塞压缩以及多种潜在的数据丢失或崩溃循环情况。此外还修复了UI显示和规则管理等多个方面的具体问题。

更新内容 （中文）

  • [变更] API：弃用 /api/v1/query 和 /api/v1/query_range 中 stats 查询参数除 true 和 all 以外的值。其他值仍启用基础统计，但现在会返回弃用警告；它们将在下一个主版本中被拒绝。#19124
  • [变更] API：/api/v1/status/config 现在在重标签配置中显式设置为空时，正确显示 separator: \"\" 和 replacement: \"\"，而非省略它们。#18653
  • [变更] 发现/ Hetzner：为 hcloud 目标移除 __meta_hetzner_datacenter 标签，遵循其从 Hetzner Cloud API 中的移除。#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
  • [性能] 抓取：无递归解析文本和 OpenMetrics 格式，防止因深度嵌套或恶意呈现输入导致的堆栈溢出。#19143
  • [性能] 抓取：减少原生直方图抓取解析分配约 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 服务发现中当服务作为插件或网络附件运行时的 panic。#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
  • [错误修复] 抓取：修复抓取管理器在关闭时以 100% CPU 运行的问题。#19149
  • [错误修复] TSDB：修复在配置文件中使用 stale_series_compaction_threshold 时可能导致静默数据丢失和潜在崩溃循环的问题。#19016
  • [错误修复] TSDB：修复在启用乱序摄入且块被压缩时重启可能丢失数据的问题。#19016
  • [错误修复] TSDB：修复 prometheus_tsdb_head_stale_series 过度计数以及序列在浮点、整数直方图和浮点直方图样本类型之间变化时被过早驱逐的问题。#19183
  • [错误修复] TSDB：修复当 Prometheus 无法打开损坏的 TSDB 时发生的协程和文件句柄泄漏。在 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

下载链接