发布日期: 2025-11-19
版本号: v3.8.0-rc.0

本次发布首次将原生直方图作为稳定功能推出，但需通过scrape_native_histogram配置项显式启用。为平稳过渡，旧功能标志--enable-feature=native-histograms在本版本（v3.8）中仍会生效，其作用是将该配置项的默认值设为true；在下一版本（v3.9）中该标志将完全失效，且默认值将固定为false。建议用户按步骤升级：首先保持标志升级至v3.8；然后根据需要在相关抓取配置中明确设置scrape_native_histogram为true或false；接着移除标志并验证功能；最后再升级至v3.9。

本次更新包含多项变更：新增Docker镜像标签、统一AWS服务发现、UI改进（如PROMQL编辑器增强、目标重标签步骤展示）、告警模板函数扩展、Promtool支持远程写入2.0等。同时优化了负值原生直方图处理、混合直方图转换、OTLP采样去重等功能的文档与实现。性能方面提升了变参函数解析速度、UI渲染效率及高警报场景下的响应。此外修复了PromQL信息函数、采样限制、TLS配置等多项缺陷，并解决了API并发与界面显示问题。

更新内容 （中文）

原生直方图用户须知

这是首个将原生直方图作为稳定功能发布的版本。但是，抓取原生直方图需要通过 scrape_native_histogram 配置设置显式启用（此版本新引入）。为了便于过渡，--enable-feature=native-histograms 标志在本版本中并非完全无效，而是将 scrape_native_histogram 的默认值更改为 true。在下一个版本（v3.9）中，该功能标志将完全失效，且 scrape_native_histogram 的默认值将始终为 false。如果您一直在使用该功能标志，建议采取以下操作：

  1. 升级到 v3.8 并保留该功能标志。一切应照常工作。
  2. 根据自身节奏，在所有相关的抓取配置中将 scrape_native_histogram 设置为 true。（scrape_native_histogram 有全局版本和每个抓取配置的版本，必要时允许进行细粒度控制。建议也在不需要抓取原生直方图的地方显式将 scrape_native_histogram 设置为 false。这样，您就不再依赖于该设置的默认值。）
  3. 移除该功能标志，并确保一切仍按预期工作。
  4. 此时您就可以准备升级到下一个版本（v3.9）了。

变更日志

  • [变更] TSDB：现在拒绝自定义边界包含 NaN 阈值的原生直方图。#17287
  • [特性] Dockerfile：向 Dockerfile 添加 OpenContainers 规范标签。#16483
  • [特性] SD：为 EC2、Lightsail 和 ECS 服务添加统一的 AWS 服务发现。#17046
  • [特性] 原生直方图现已成为稳定但可选的特性，使用 scrape_native_histogram 配置设置。#17232 #17315
  • [特性] UI：在 PromQL 编辑器中支持 anchored 和 smoothed 关键字。#17239
  • [特性] UI：显示每个发现目标的详细重标签步骤。#17337
  • [特性] 告警：向模板函数添加 urlQueryEscape。#17403
  • [特性] Promtool：通过 --protobuf_message 标志为 promtool push metrics 添加 Remote-Write 2.0 支持。#17417
  • [增强] 澄清关于处理负数原生直方图的文档。#17249
  • [增强] Mixin：为 remote-write 仪表板添加静态 UID。#17256
  • [增强] PromQL：调和 Add 和 Sub 中不匹配的 NHCB 边界。#17278
  • [增强] 告警：为尚未评估的告警规则添加 “unknown” 状态。#17282
  • [增强] 抓取：允许同时使用经典直方图到 NHCB 的转换与零时间戳摄入。#17305
  • [增强] UI：在解释中添加 smoothed/anchored。#17334
  • [增强] OTLP：去重同一时间戳下同一序列的任何 target_info 样本。#17400
  • [增强] 在 sigv4 配置部分记录 use_fips_sts_endpoint。#17304
  • [增强] 记录 Prometheus Agent。#14519
  • [性能] PromQL：加快可变参数函数的解析速度。#17316
  • [性能] UI：通过不渲染折叠内容来加快告警/规则/… 页面的加载速度。#17485
  • [性能] UI：提升在 PromQL 编辑器中获取标签名称和值的性能。#17194
  • [性能] UI：通过虚拟滚动加快 /alerts 页面（针对大量触发告警）。#17254
  • [缺陷修复] PromQL：修复 info 函数在高频更新序列上的切片索引错误。#17199
  • [缺陷修复] API：减少 /api/v1/targets 上的锁争用。#17306
  • [缺陷修复] PromQL：在聚合中一致处理 gauge 与 counter 直方图。#17312
  • [缺陷修复] TSDB：允许 NHCB 将 -Inf 作为第一个自定义值。#17320
  • [缺陷修复] UI：修复从 API 重复加载数据以加快某些页面的渲染速度。#17357
  • [缺陷修复] 旧版 UI：修复 createExpressionLink 以正确构建 /graph URL，使从告警/规则页面的链接再次可用。#17365
  • [缺陷修复] PromQL：避免解析格式错误的 info 调用时发生 panic。#17379
  • [缺陷修复] PromQL：在执行 sample_limit 时包含直方图。#17390
  • [缺陷修复] 配置：修复如果缺少 TLS CA 文件时发生 panic 的问题。#17418
  • [缺陷修复] PromQL：修复当经典直方图和 NHCB 的下界在第一个桶中时的 histogram_fraction 计算。#17424

更新内容 （原始）

Note for users of Native Histograms

This is the first release with Native Histograms as a stable feature. However, scraping Native Histograms has to be activated explicitly via the scrape_native_histogram config setting (newly introduced in this release). To ease the transition, the --enable-feature=native-histograms flag is not a complete no-op in this release, but changes the default value of scrape_native_histogram to true. In the next release (v3.9), the feature flag will be a complete no-op, and the default value of scrape_native_histogram will always be false. If you have been using the feature flag so far, the recommended course of action is the following:

  1. Upgrade to v3.8 and keep the feature flag. Everything should work as before.
  2. At your own pace, set scrape_native_histogram to true in all relevant scrape configs. (There is a global and a per-scrape-config version of scrape_native_histogram, allowing granular control if needed. It is a good idea to also set scrape_native_histogram explicitly to false where you do not want to scrape Native Histograms. In this way, you do not depend on the default value of the setting anymore.)
  3. Remove the feature flag and make sure that everything still works as intended.
  4. Now you are ready for an upgrade to the next release (v3.9).

Changelog

  • [CHANGE] TSDB: Native Histogram Custom Bounds with a NaN threshold are now rejected. #17287
  • [FEATURE] Dockerfile: Add OpenContainers spec labels to Dockerfile. #16483
  • [FEATURE] SD: Add unified AWS service discovery for ec2, lightsail and ecs services. #17046
  • [FEATURE] Native histograms are now a stable, but optional feature, use the scrape_native_histogram config setting. #17232 #17315
  • [FEATURE] UI: Support anchored and smoothed keyword in promql editor. #17239
  • [FEATURE] UI: Show detailed relabeling steps for each discovered target. #17337
  • [FEATURE] Alerting: Add urlQueryEscape to template functions. #17403
  • [FEATURE] Promtool: Add Remote-Write 2.0 support to promtool push metrics via the --protobuf_message flag. #17417
  • [ENHANCEMENT] Clarify the docs about handling negative native histograms. #17249
  • [ENHANCEMENT] Mixin: Add static UID to the remote-write dashboard. #17256
  • [ENHANCEMENT] PromQL: Reconcile mismatched NHCB bounds in Add and Sub. #17278
  • [ENHANCEMENT] Alerting: Add “unknown” state for alerting rules that haven’t been evaluated yet. #17282
  • [ENHANCEMENT] Scrape: Allow simultaneous use of classic histogram → NHCB conversion and zero-timestamp ingestion. #17305
  • [ENHANCEMENT] UI: Add smoothed/anchored in explain. #17334
  • [ENHANCEMENT] OTLP: De-duplicate any target_info samples with the same timestamp for the same series. #17400
  • [ENHANCEMENT] Document use_fips_sts_endpoint in sigv4 config sections. #17304
  • [ENHANCEMENT] Document Prometheus Agent. #14519
  • [PERF] PromQL: Speed up parsing of variadic functions. #17316
  • [PERF] UI: Speed up alerts/rules/… pages by not rendering collapsed content. #17485
  • [PERF] UI: Performance improvement when getting label name and values in promql editor. #17194
  • [PERF] UI: Speed up /alerts for many firing alerts via virtual scrolling. #17254
  • [BUGFIX] PromQL: Fix slice indexing bug in info function on churning series. #17199
  • [BUGFIX] API: Reduce lock contention on /api/v1/targets. #17306
  • [BUGFIX] PromQL: Consistent handling of gauge vs. counter histograms in aggregations. #17312
  • [BUGFIX] TSDB: Allow NHCB with -Inf as the first custom value. #17320
  • [BUGFIX] UI: Fix duplicate loading of data from the API speed up rendering of some pages. #17357
  • [BUGFIX] Old UI: Fix createExpressionLink to correctly build /graph URLs so links from Alerts/Rules work again. #17365
  • [BUGFIX] PromQL: Avoid panic when parsing malformed info call. #17379
  • [BUGFIX] PromQL: Include histograms when enforcing sample_limit. #17390
  • [BUGFIX] Config: Fix panic if TLS CA file is absent. #17418
  • [BUGFIX] PromQL: Fix histogram_fraction for classic histograms and NHCB if lower bound is in the first bucket. #17424

下载链接