Prometheus 3.14.0 升级笔记：query stats 参数弃用、duration expressions 默认开启后要改什么
版本日期 2026-08-17。CHANGELOG 全文见 prometheus/prometheus CHANGELOG.md。
/api/v1/query 与 query_range 的 stats 参数开始弃用
stats 参数里除 true 与 all 之外的取值已经弃用（PR #19124）。当前行为是：这些取值仍然启用基础统计，和以前返回的内容一致，只是响应里多一条弃用警告；到下一个主版本会被直接拒绝。
也就是说，升级后接口不会坏，坏的是下个大版本，而中间的信号只有一条容易被日志和采集链路吞掉的警告。先把调用方找出来：
grep -rn "stats=" /path/to/scripts /etc/grafana/provisioning /etc/prometheus
处理方式只有两种：确实要看统计数据就统一写成 stats=true 或 stats=all；不需要统计就把参数整段删掉，不要继续留一个即将被拒绝的取值。
duration expressions 默认开启，promql-duration-expr 变成 no-op
--enable-feature=promql-duration-expr 所控制的 duration expressions 现在默认启用，该特性开关变成 no-op（PR #19033）。两个方向都要检查：
- 启动参数里还写着
promql-duration-expr的，可以删掉。留着不报错，但会让人以为这个能力是被开关控制的。 - 之前没开这个开关的实例，升级后 duration 表达式直接生效，原先会被拒绝的写法现在会正常求值。告警规则和 recording rule 里如果有这类表达式，语义变化是升级那一刻发生的，而不是等你改配置。
first_over_time 转正
first_over_time 转为稳定特性，不再需要 promql-experimental-functions 开关（PR #19093）。如果当初开 promql-experimental-functions 只是为了用它，可以从 --enable-feature 里去掉这一项；如果还有别的实验函数在依赖这个开关，则维持原样。
顺带确认一下用到 first_over_time 的告警规则：既然函数已经稳定，规则本身不需要任何改动，要改的只是启动参数。
OCI 服务发现新增，以及一条会打断 relabel 的 Hetzner 变更
Discovery 新增 oci_sd_configs，用于 Oracle Cloud Infrastructure 计算服务发现（PR #18919）。
同一批 discovery 变更里有一条会直接影响现有配置：hcloud 目标的 __meta_hetzner_datacenter 标签被移除，跟随该字段从 Hetzner Cloud API 下线（PR #19269）。引用这个标签的 relabel 规则会拿不到值，keep/drop 判断可能静默失效，导致目标被错误保留或丢弃：
grep -rn "__meta_hetzner_datacenter" /etc/prometheus
另外 /api/v1/status/config 现在会在 relabel 配置中显式写出 separator:"" 与 replacement:""，而不是省略它们（PR #18653）。用接口做配置比对或 diff 的脚本会出现一次性的噪音，先把基准更新掉再跑。
use-start-timestamps：rate/increase 的另一种外推
这是一组实验性能力，统一挂在 use-start-timestamps 开关下（PR #19089、PR #18619）：
- 新增实验性函数
start_timestamp(instant-vector)； rate()与increase()可以改用 start timestamps 做外推，替代默认的速率外推方式；- TSDB 侧另有在直方图与 float 直方图中编码 start timestamps 的实验性支持，开关为
histograms-st-encoding（PR #18609）。
实验特性不要直接进生产告警。先在小范围实例上打开，对同一个时间窗口把 rate()/increase() 的两种外推结果并排看一段时间，确认差异在可接受范围内再考虑推广。
OTLP 属性名碰撞会有警告
OTLP 属性名 sanitize 后可能碰撞到同一个 Prometheus 标签，例如 k8s.pod.name 与 k8s_pod_name 都会变成 k8s_pod_name。现在遇到这种情况会发出警告，并暴露计数器 prometheus_api_otlp_translation_warnings_total，按 category 标签区分（PR #18957）。给这个计数器配一条告警，就能在数据被两个属性互相覆盖之前发现翻译问题。
升级前的检查清单
grep -rn "stats="，把除true/all之外的值清理掉。- 从启动参数移除已变成 no-op 的
promql-duration-expr，并确认没有规则依赖 duration 表达式报错。 - 确认
first_over_time不再需要promql-experimental-functions。 grep -rn "__meta_hetzner_datacenter"，重写受影响的 relabel 规则。- 更新
/api/v1/status/config的比对基准。 - 查询响应中的弃用警告纳入观察项，别等到下个主版本被拒绝时才发现。
参考：https://github.com/prometheus/prometheus/blob/main/CHANGELOG.md