发布日期: 2025-12-02
版本号: v3.8.0

该版本（v3.8）是 Prometheus 的一个渐进式更新。主要变化如下：

  1. 原生直方图（Native Histograms）功能现已稳定，但默认处于禁用状态。需要通过配置项 scrape_native_histograms 显式启用。从旧版本（使用 --enable-feature=native-histograms 标志）升级的建议路径是：先升级到 v3.8 并保留原特性标志以确保兼容；然后根据需要在配置中启用 scrape_native_histograms；最后移除特性标志，并为未来版本（v3.9，届时特性标志将失效且默认值为 false）做好准备。
  2. 其他重要变更包括：远程写入（Remote-write）2.0 规范更新；新增 OAuth2 JWT 认证、统一 AWS 服务发现、PromQL 编辑器关键字支持、告警规则的“未知”状态等功能；增强了 PromQL 对直方图处理的兼容性、OTLP 去重、UI 渲染性能等；并修复了包括 PromQL 解析、API 锁竞争、配置项处理等在内的多个 bug。

总体而言，这是一个以功能稳定化和性能优化为主的更新版本，用户可根据自身需求平滑过渡到新版本。

更新内容 （中文）

原生直方图用户注意事项

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

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

变更日志

  • [变更] 远程写入2（接收）：更新到 2.0-rc.4 规范。“created timestamp” (CT) 现在称为 “start timestamp” (ST)。 #17411
  • [变更] 时序数据库：具有 NaN 阈值的原生直方图自定义边界现在被拒绝。 #17287
  • [功能] OAuth2：支持 jwt-bearer 授权类型 (RFC7523 3.1)。 #17592
  • [功能] Dockerfile：为 Dockerfile 添加 OpenContainers 规范标签。 #16483
  • [功能] 服务发现：为 EC2、Lightsail 和 ECS 服务添加统一的 AWS 服务发现。 #17046
  • [功能] 原生直方图现在是稳定但可选的功能，使用 scrape_native_histograms 配置设置。 #17232 #17315
  • [功能] UI：在 PromQL 编辑器中支持 anchored 和 smoothed 关键字。 #17239
  • [功能] UI：为每个发现的目标显示详细的重标签步骤。 #17337
  • [功能] 告警：在模板函数中添加 urlQueryEscape。 #17403
  • [功能] Promtool：通过 --protobuf_message 标志为 promtool push metrics 添加远程写入2.0支持。 #17417
  • [增强] 澄清关于处理负原生直方图的文档。 #17249
  • [增强] Mixin：为远程写入仪表板添加静态 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 函数在 churn 序列上的切片索引错误。 #17199
  • [修复] API：减少 /api/v1/targets 上的锁争用。 #17306
  • [修复] PromQL：一致处理聚合中的 gauge 与 counter 直方图。 #17312
  • [修复] 时序数据库：允许 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_histograms 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_histograms to true. In the next release (v3.9), the feature flag will be a complete no-op, and the default value of scrape_native_histograms 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_histograms to true in all relevant scrape configs. (There is a global and a per-scrape-config version of scrape_native_histograms, allowing granular control if needed. It is a good idea to also set scrape_native_histograms 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] Remote-write 2 (receiving): Update to 2.0-rc.4 spec. “created timestamp” (CT) is now called “start timestamp” (ST). #17411
  • [CHANGE] TSDB: Native Histogram Custom Bounds with a NaN threshold are now rejected. #17287
  • [FEATURE] OAuth2: support jwt-bearer grant-type (RFC7523 3.1). #17592
  • [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_histograms 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

下载链接