Prometheus 3.x 特性开关Feature Flags深度指南从 --enable-feature 到源码级验证【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus本文基于当前仓库的 docs/feature_flags.md 编写系统讲解 Prometheus 中所有默认关闭的实验性或破坏性特性开关如何通过--enable-feature启用它们、每个开关改变了哪些底层行为、以及仓库源码中的实际实现位置与验证方式。读完本文你可以安全地评估并开启 exemplar 存储、Start Timestamp 全链路、PromQL 扩展语法、OTLP delta 摄入、Search API 等功能并理解其废弃与迁移路径。特性开关的工作机制Prometheus 将默认禁用的特性因为它们是破坏性变更或仍被视为实验性统一收纳在 docs/feature_flags.md 中。行为变化会通过发布说明通告且这些特性在未来版本中可能被默认启用。启用方式是命令行参数--enable-feature接受逗号分隔的多个特性名prometheus --enable-featureexemplar-storage,metadata-wal-records从源码看该参数的解析集中在 cmd/prometheus/main.go 的setFeatureListOptions函数中函数遍历featureList并用逗号拆分每个特性名对应一个case分支向flagConfig中设置具体的布尔开关例如c.tsdb.EnableExemplarStorage、c.scrape.ParseST、c.web.EnableSearch等。几个值得注意的实现细节未知选项只告警不报错default分支记录Unknown option for --enable-feature的 Warn 日志cmd/prometheus/main.go即拼写错误的特性名不会导致启动失败需留意启动日志。互斥校验otlp-deltatocumulative与otlp-native-delta-ingestion不能同时启用冲突时启动直接返回错误cmd/prometheus/main.go。运行特性注册表部分特性还会写入 util/features/features.go 中的全局特性注册表按api、tsdb、promql、scrape等类别组织供 HTTP API 上报。启动后可通过GET /api/v1/features端点查询当前构建支持的全部特性及各特性是否启用cmd/prometheus/features_test.go 中的TestFeaturesAPI正是通过启动真实进程、请求该端点并与testdata/features.json黄金文件比对来验证的。有效的选项全集来自 cmd/prometheus/main.go 中该参数的帮助文本concurrent-rule-eval, created-timestamp-zero-ingestion, delayed-compaction, exemplar-storage, extra-scrape-metrics, histograms-st-encoding, memory-snapshot-on-shutdown, metadata-wal-records, old-ui, openmetrics2, otlp-deltatocumulative, otlp-native-delta-ingestion, promql-binop-fill-modifiers, promql-delayed-name-removal, promql-experimental-functions, promql-extended-range-selectors, promql-per-step-stats, search-api, st-storage, st-synthesis, type-and-unit-labels, use-start-timestamps, use-uncached-io, xor2-encoding, zstd-scrape。此外--enable-feature的历史包袱同样由这段 switch 处理auto-reload-config已废弃提示改用--config.auto-reloadpromql-duration-expr、ooo-native-histograms已永久启用no-opnative-histograms提示改用抓取配置项scrape_native_histograms。这些处理逻辑同样位于 cmd/prometheus/main.go。存储层特性Exemplars 存储exemplar-storageOpenMetrics 规范允许抓取目标为某些指标附带 exemplar——指向 MetricSet 之外数据的引用最常见的用途是程序 trace ID。实现上exemplar 存储是一个固定大小的环形缓冲circular buffer在内存中为所有序列保存 exemplar。启用该特性后Prometheus 抓取到的 exemplar 才会被保存。可通过配置文件中 storage/exemplars 区块按“exemplar 数量”控制环形缓冲大小。单个只带trace_idjaeger-trace-id的 exemplar 大约占用 100 字节内存。启用后exemplar 还会被追加写入 WAL 做本地持久化保存时长取决于 WAL 保留期。源码侧该开关直接映射为c.tsdb.EnableExemplarStoragecmd/prometheus/main.go并在配置热重载时被透传给reloadConfig的加载器cmd/prometheus/main.go。关闭时的内存快照memory-snapshot-on-shutdown关闭进程时对内存中的 chunk 连同序列信息做快照并落盘。这样启动时可以直接用该快照恢复内存状态并 m-map 磁盘上的 chunkWAL 回放只需要处理快照之外的 WAL 片段从而显著降低启动时间。延迟 Head 压缩启动delayed-compaction为 Head 压缩的启动时间加上一个不超过 chunk range 10% 的随机偏移帮助同一台宿主机上的多个 Prometheus 实例错开压缩时机、减轻共享资源磁盘、CPU的瞬时压力。约束包括只有自动触发的 Head 压缩及其直接派生的操作会受此延迟影响若连续多次 Head 压缩都可能发生只有第一次会经历延迟延迟期间 Head 照常工作继续提供查询与样本追加延迟只改变压缩开始的时间点产出的 block 时间对齐方式与不延迟时完全一致。绕过页缓存的 IOuse-uncached-io实验性特性仅在 Linux 上可用。启用后 chunk 写入绕过页缓存当前实现为 direct I/O主要目标是消除页缓存行为带来的困惑防止因缓存“虚高”增长导致的内存过量分配。注意该特性在启用时会通过fileutil.UncachedIOSupported()检测平台支持不支持则直接返回错误cmd/prometheus/main.go。元数据 WAL 记录metadata-wal-records启用后Prometheus 将元数据保存在内存中并按序列粒度把元数据变化作为 WAL 记录跟踪。如果你希望通过新版 Remote Write 2.0 发送元数据必须启用此特性。XOR2 chunk 编码xor2-encoding注意此特性开关已废弃。XOR2 float chunk 编码已经稳定应改用配置文件中storage.tsdb段的chunk_encoding.floats字段见 配置文档来显式选择。该开关目前仅把 float chunk 编码的默认值设为xor2在未来大版本中将变为 no-op对应源码中的告警逻辑见 cmd/prometheus/main.go。另外st-storage特性也会自动选择 XOR2 作为默认 float chunk 编码因为 XOR chunk 无法保存 Start Timestamp。Histogram ST chunk 编码histograms-st-encoding警告这是高度实验性且有风险的设置用histogramST和floathistogramST编码的 chunk无法被不支持该编码的旧版 Prometheus 读取。一旦启用并写入数据若回退版本需要手动从磁盘删除这些 block否则所有查询都会报错。编码方案仍在实验中任意版本都可能变化跨版本持久化 block 数据会丢失。编码很新下游工具与 LTS 系统例如 Thanos sidecar 上传的 block可能尚不支持。该设置启用针对原生直方图与 float 直方图样本的新histogramST、floathistogramSTchunk 编码它们在对应直方图 chunk 格式上扩展了 Start TimestampST头与逐样本 ST 编码作用相当于 XOR2 编码 对 float chunk 做的事。该开关不影响 float chunk。st-storage特性会自动启用这些直方图编码若单独启用本开关而未启用st-storage则只使用支持 ST 的直方图 chunk 编码但不会保存摄入时收到的 Start Timestamp。Start TimestampST全家桶Prometheus 围绕“指标样本携带开始时间”提供了一组渐进式特性理解它们的关系是安全启用的前提。ST 零值注入created-timestamp-zero-ingestion说明CreatedTimestamp 特性为保持一致性已更名为 StartTimestamp此特性开关仍沿用旧名以保持稳定性。启用 Start Timestamp 的摄入在合适时 ST 会被注入为值为 0 的样本。目前 Prometheus 支持在PrometheusProto与OpenMetrics1.0.0两种格式上承载 ST其中推荐PrometheusProto——OpenMetrics 1.0 的 ST 信息通过metric_created指标传递解析这类指标既易出错又昂贵增加开销还要小心不要让额外的_created指标污染你的 Prometheus。因此启用created-timestamp-zero-ingestion后Prometheus 会把全局scrape_protocols的默认值改为[PrometheusProto, OpenMetricsText1.0.0, OpenMetricsText0.0.1, PrometheusText0.0.4]即优先协商 Prometheus Protobuf 协议除非显式设置了其他scrape_protocols。从源码看正是把全局默认值替换为config.DefaultProtoFirstScrapeProtocols实现的cmd/prometheus/main.go该协议列表定义在 config/config.go。除了 Prometheus 侧启用被抓取的应用也必须暴露 ST 才能生效。ST 原生存储st-storage启用逐样本的 Start Timestamp 存储贯穿 WAL、TSDB/Agent 与 Remote Write 2.0能够完整保留抓取与接收协议呈现的精确 ST 值。未来该特性将取代通过注入合成 0 样本的created-timestamp-zero-ingestion。目前支持 ST 的格式同样为PrometheusProto与OpenMetrics1.0.0推荐PrometheusProtoST 传递更高效。同样要求被抓取应用暴露 ST。已知限制实验性特性引入新的 WAL 记录类型SamplesV2只能被 Prometheus 3.11 或更高版本回放为了持久化TSDB block该特性会自动为 float 启用 XOR2 chunk 格式、为原生直方图启用 ST chunk 格式与chunk_encoding.floats: xor2和 histograms-st-encoding 开关独立启用时相同。若在配置文件中显式写chunk_encoding.floats: xor且st-storage处于激活状态配置重载时会被拒绝因为 XOR chunk 不保存 Start Timestamp。这些约束在实验阶段结束后可能调整原生直方图与 NHCB 在其他方面的 ST 支持仍在推进中PromQL 层面对 ST 的使用不在本特性范围内见下条use-start-timestamps。源码中该开关同时设置了scrape.ParseST、tsdb.EnableSTStorage、FloatChunkEncoding EncXOR2、EnableHistogramSTEncoding与 agent 端开关并同样切换 proto 优先的抓取协议默认值cmd/prometheus/main.go。ST 在 PromQL 函数中的使用use-start-timestamps启用rate()、irate()、increase()、start_timestamp()等 PromQL 函数对 Start Timestamp 的使用。注意该特性目前不支持扩展范围选择器promql-extended-range-selectors。ST 合成st-synthesis当源端不提供 ST 时对累积型指标Counter、经典直方图、原生直方图合成 Start Timestamp。其思路类似于 OpenTelemetry Collector 社区贡献的 metricstarttimeprocessor 的“减去初始点”策略跟踪前值以检测重置并从第一个样本起减去初始参考点合成一条从零开始的时间线。实验性特性的注意事项特性开启时第一个样本会被丢弃用于建立 ST 参考点。因此若某序列只上报过一个点开启后可能导致该序列没有任何样本入库合成能给出准确的 Start Timestamp 且保持计数器速率准确但原始计数器值将与抓取值不同——第一个点被丢弃、其时间戳被用作后续所有点的起始时间戳后续所有点都会相对该被丢弃的点做归一化减去它。相当于用原始数据创建了一条已知起始时间的新计数器流合成仅对抓取数据生效Remote Write 与 OTLP 接收器尚未实现合成要求样本有序因此没有 ST 的累积样本即使设置了tsdb.out_of_order_time_window也会因乱序被拒绝若某序列的追加失败例如因乱序样本被拒该序列的合成状态会被清除失败后的下一个样本会被当作“第一个样本”再次丢弃以建立新参考点。PromQL 相关特性逐步统计promql-per-step-stats启用后在查询请求中传statsall会返回逐步骤per-step统计包含totalQueryableSamples / totalQueryableSamplesPerStep查询期间加载的样本总数。对rate、sum_over_time这类 range-vector 函数在多步求值时每一步都会计入完整窗口同一点可能在多个步骤被重复计数。samplesRead / samplesReadPerStep样本读取I/O总数。range 查询中的 range-vector 函数只计每步的新增点第 0 步计完整窗口后续步骤只计上一步未出现的点其他查询类型下该值等于 totalQueryableSamples。peakSamples求值期间内存中的峰值样本数用于query.max-samples限制。服务端另有两个可观测计数器prometheus_engine_query_samples_total按步计完整窗口的加载样本数与prometheus_engine_query_samples_read_totalrange-vector 按步计增量读取数。若引擎或查询层面任一未启用该特性逐步骤统计将完全不计算。实验性 PromQL 函数promql-experimental-functions启用被视为实验性的 PromQL 函数。这些函数的名称、语法或语义可能改变甚至可能整体被移除。延迟__name__标签移除promql-delayed-name-removal启用后Prometheus 改变 PromQL 查询结果中移除__name__标签的方式对于需要移除的函数与表达式把移除延迟到查询求值的最后一步而不是每求值一次会派生指标的表达式/函数就移除一次。好处允许通过label_replace、label_join可选地保留__name__避免对__name__标签应用正则匹配器时出现 vector cannot contain metrics with the same labelset 错误。限制与风险分开求值查询的一部分仍会触发 labelset 冲突——手动或用 PromLens 类工具分析中间结果时常见若查询引用了已被移除的__name__标签行为可能改变例如sum by (__name__) (rate({foobar}[5m]))。这类查询很少见且容易修复——上例中去掉by (__name__)在无特性时结果不变在启用特性时则能修复潜在问题理论上可构造聚合到__name__、把“延迟移除”与“未移除”的样本放进同一分组此时该分组的名称会被移除——这种情形在实用查询中几乎不会出现。扩展范围选择器promql-extended-range-selectors为 PromQL 的 range 与 instant 选择器启用实验性anchored与smoothed修饰符让你在rate、increase等函数中更精细地控制 range 边界处理尤其在缺失或不规则数据下。注意原生直方图尚不受扩展范围选择器支持且不支持子查询。anchored在 range 起点使用 lookback delta 内最近的样本若 lookback delta 内无样本则使用 range 内第一个样本range 终点同样使用 range 内最后一个样本。不做外推或插值适合直接获取样本值之间的差。适用于resets、changes、rate、increase、delta。示例increase(http_requests_total[5m] anchored)注意increase配合 anchored 修饰符时返回结果为整数。smoothedrange 选择器在 range 边界处线性插值利用边界前后两侧的样本值做更稳健的估计可抗不规则抓取与缺失样本但它需要求值区间之后的样本才能正确工作见下方规则告警提示。instant 选择器则在求值时间戳处用紧邻前后的两个样本线性插值。适用于rate、increase、delta。示例rate(http_requests_total[step()] smoothed)告警与录制规则注意smoothed需要求值区间之后的样本直接在规则中使用通常会低估结果求值时刻拿不到未来样本。要安全地在规则里用smoothed必须给规则组设置query_offset确保计算窗口完全落在过去、所需样本都已可用。关键告警建议至少偏移一个抓取间隔非关键或希望更强容错容忍漏抓的场景可考虑更大偏移多个抓取间隔。二元运算 fill 修饰符promql-binop-fill-modifiers为 PromQL 二元运算符启用实验性的fill()、fill_left()、fill_right()修饰符允许为二元运算一侧缺失的匹配项填入指定的默认样本值。示例rate(successful_requests[5m]) fill(0) rate(failed_requests[5m])更多细节与示例参见 fill 修饰符文档。抓取与协议相关特性额外抓取指标extra-scrape-metrics注意此特性开关已废弃请改用extra_scrape_metrics配置项可在全局与抓取配置两级设置该开关将在未来大版本移除详见配置文档。启用后每次实例抓取会在以下额外时间序列中存储一个样本scrape_timeout_seconds该目标的scrape_timeout配置值配合scrape_duration_seconds / scrape_timeout_seconds可观察各目标距超时的余量scrape_sample_limit该目标的sample_limit配置值配合scrape_samples_post_metric_relabeling / scrape_sample_limit观察距限制的余量。注意未配置限制时该值为 0上述查询会出现除以 0 得到Inf若只想查“配置了限制”的目标用scrape_samples_post_metric_relabeling / (scrape_sample_limit 0)scrape_body_size_bytes最近一次成功抓取响应的解压后大小。因超出body_size_limit而失败的抓取报-1其他抓取失败报0。Zstandard 抓取压缩zstd-scrape启用后Prometheus 除了 gzip 之外还会在抓取请求中宣告支持 Zstandard 压缩的响应。解压后的响应仍受配置的body_size_limit约束。OpenMetrics 2.0openmetrics2启用对暴露 OpenMetrics 2.0 文本格式的抓取目标的支持内容类型为application/openmetrics-text; version2.0.0。OpenMetrics 2.0 支持仍是实验性的解析器尚未稳定今天 Prometheus 接受的暴露格式未来版本可能拒绝请勿在生产中依赖当前行为。关闭该开关时OpenMetrics 2.0 内容类型会被当作不支持的内容类型处理若目标配置了fallback_scrape_protocol则回退使用它否则抓取失败。如果你正在实现 OpenMetrics 2.0 exporter 或客户端库请注意被 Prometheus 成功抓取不等于你的输出符合规范请以官方 OpenMetrics 2.0 迁移指南为准。类型与单位标签type-and-unit-labels启用后Prometheus 会按 PROM-39 提案的设计开始注入额外的保留标签__type__与__unit__。这些标签来源于既有抓取与摄入格式OpenMetrics Text、Prometheus Text、Prometheus Proto、Remote Write 2、OTLP的元数据结构用户提供的同名__type__、__unit__标签会被覆盖。PromQL 层会以与__name__相同的方式处理这些标签例如在-、等运算中被丢弃并受promql-delayed-name-removal特性影响。该特性让重要元数据信息可以直接随样本与 PromQL 层使用尤其适合想按类型或单位选择指标的用户想处理同名不同类型/单位序列的场景例如原生直方图迁移、或来自 OTLP 端点未经翻译的 OpenTelemetry 指标。后续还有依赖此特性的规划工作例如在类型误用时提供帮助的 PromQL 体验改进、自动重命名、delta 类型等。与元数据记录的行为启用本特性且存在元数据 WAL 记录时若两者给出的 type 或 unit 不一致小概率情况Prometheus 输出倾向于__type__/__unit__标签的值。例如 Remote Write 2.0 场景下即使元数据记录可能因 bug说是 counter只要__type__gauge远端时间序列会被设为 gauge。OTLP 相关特性OTLP delta 转累积otlp-deltatocumulative启用后Prometheus 不再丢弃 delta 时序temporality的 OTLP 指标而是把它们转换为等价的累积形式。不能与otlp-native-delta-ingestion同时启用启动时会报错见前文互斥校验。该转换复用 OTel Collector 的 deltatocumulative 处理器默认设置。delta 转换需要在内存中保持按序列聚合 delta 变化的状态Prometheus 重启后该状态丢失累积序列会从零重新聚合表现为一次计数器重置。该状态会周期性清除不活跃的序列按max_stale设置。启用后可能对性能产生负面影响因为内存状态由互斥锁保护纯累积的 OTLP 请求不受影响。OTLP 原生 delta 支持otlp-native-delta-ingestion启用后允许原生摄入delta 时序的 OTLP 指标原样存储原始样本值不做转换。不能与otlp-deltatocumulative同时启用。当前StartTimeUnixNano字段被忽略delta 指标被赋予“未知”的指标元数据类型。delta 支持处于非常早期阶段摄入与查询流程未来可能变化参见 prometheus/proposals 中第 48 号提案。查询建议标准 PromQL 计数器函数rate()、increase()面向累积指标设计用于 delta 指标会给出错误结果。目前要获得类似效果请用sum_over_time()sum_over_time(delta_metric[range])在指定时间范围内对 delta 值求和sum_over_time(delta_metric[range]) / range计算 delta 指标按秒速率。若range不是指标采集间隔的整数倍上述写法可能不理想。例如指标采集间隔为 10m而你执行sum_over_time(delta_metric[1m]) / 1m1m step的 range 查询图表会每 10 分钟出现一个高速率单点而不是 10 个点上的较低恒定值。当前已知坑delta 指标若通过federation暴露当摄入间隔与联邦端点的抓取间隔不一致时数据可能被错误采集难以判断某指标是 delta 还是累积时序——指标名与标签中没有时序提示。目前若同时摄入 delta 与累积指标建议显式添加自定义标签加以区分。未来计划引入类型标签来一致地区分指标类型并可能让 PromQL 函数类型感知例如对 delta 指标使用仅适用于累积的函数时给出警告同一时间戳摄入多个样本时只保留其中一个点样本不会求和这是 Prometheus 的通用行为——相同时间戳的重复样本会被拒绝。任何聚合都必须在发送样本到 Prometheus 之前完成。规则引擎与 API/UI 特性独立规则并发求值concurrent-rule-eval默认情况下规则组之间并发执行但组内规则串行执行——因为规则可能把前一条规则的输出作为自己的输入。若规则间没有可检测的依赖关系就没有必要串行运行。启用concurrent-rule-eval后规则组内不依赖其他规则的规则会并发求值可能改善规则组求值延迟与资源利用率代价是增加并发查询负载。并发规则求值数量由--rules.max-concurrent-evals配置默认值为 4见 cmd/prometheus/main.go 的默认值注册设置该值时可能需要同步调整query.max-concurrency。Search APIsearch-api启用实验性的搜索 API 端点支持模糊匹配与过滤地发现指标名、标签名与标签值详见搜索 API 文档。配套的--web.search.max-limit标志默认10000为搜索端点接受的limit查询参数设置硬性上限超限请求返回 HTTP 400默认响应限制100会被静默钳制到该上限因此运维调小上限不会破坏不带limit的请求设为0表示完全禁用上限——不建议在可信网络之外暴露端点时这样做否则单个客户端可一次性请求整个索引。旧版 Web UIold-ui回退到提供旧版Prometheus 2.xWeb UI而不是新 UI。随 Prometheus 3.0 发布的新 UI 是一次完全重写目标是更干净、少干扰、内部实现更现代但功能尚不完全、也未充分经生产检验部分用户仍可能偏好旧 UI。启用与验证的实操清单启用启动命令追加--enable-featurename1,name2注意st-storage会连带启用 XOR2 与直方图 ST 编码并与created-timestamp-zero-ingestion一样把默认scrape_protocols切换为 proto 优先列表config/config.go。核对日志启动时每个开关都会输出对应的 Info/Warn 日志如 Experimental in-memory exemplar storage enabled废弃选项extra-scrape-metrics、xor2-encoding等会输出明确的迁移告警未知名称只有 Warn。验证运行态访问GET /api/v1/features按类别查看构建支持的特性与启用状态该端点的回归行为由 cmd/prometheus/features_test.go 的TestFeaturesAPI测试保障。迁移提示extra-scrape-metrics→ 配置项extra_scrape_metricsxor2-encoding→ 配置项storage.tsdb.chunk_encoding.floats: xor2auto-reload-config→ 命令行--config.auto-reload。迁移后应移除这些开关避免未来大版本中行为变化。【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Prometheus 3.x 特性开关（Feature Flags）深度指南：从 --enable-feature 到源码级验证
Prometheus 3.x 特性开关Feature Flags深度指南从 --enable-feature 到源码级验证【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus本文基于当前仓库的 docs/feature_flags.md 编写系统讲解 Prometheus 中所有默认关闭的实验性或破坏性特性开关如何通过--enable-feature启用它们、每个开关改变了哪些底层行为、以及仓库源码中的实际实现位置与验证方式。读完本文你可以安全地评估并开启 exemplar 存储、Start Timestamp 全链路、PromQL 扩展语法、OTLP delta 摄入、Search API 等功能并理解其废弃与迁移路径。特性开关的工作机制Prometheus 将默认禁用的特性因为它们是破坏性变更或仍被视为实验性统一收纳在 docs/feature_flags.md 中。行为变化会通过发布说明通告且这些特性在未来版本中可能被默认启用。启用方式是命令行参数--enable-feature接受逗号分隔的多个特性名prometheus --enable-featureexemplar-storage,metadata-wal-records从源码看该参数的解析集中在 cmd/prometheus/main.go 的setFeatureListOptions函数中函数遍历featureList并用逗号拆分每个特性名对应一个case分支向flagConfig中设置具体的布尔开关例如c.tsdb.EnableExemplarStorage、c.scrape.ParseST、c.web.EnableSearch等。几个值得注意的实现细节未知选项只告警不报错default分支记录Unknown option for --enable-feature的 Warn 日志cmd/prometheus/main.go即拼写错误的特性名不会导致启动失败需留意启动日志。互斥校验otlp-deltatocumulative与otlp-native-delta-ingestion不能同时启用冲突时启动直接返回错误cmd/prometheus/main.go。运行特性注册表部分特性还会写入 util/features/features.go 中的全局特性注册表按api、tsdb、promql、scrape等类别组织供 HTTP API 上报。启动后可通过GET /api/v1/features端点查询当前构建支持的全部特性及各特性是否启用cmd/prometheus/features_test.go 中的TestFeaturesAPI正是通过启动真实进程、请求该端点并与testdata/features.json黄金文件比对来验证的。有效的选项全集来自 cmd/prometheus/main.go 中该参数的帮助文本concurrent-rule-eval, created-timestamp-zero-ingestion, delayed-compaction, exemplar-storage, extra-scrape-metrics, histograms-st-encoding, memory-snapshot-on-shutdown, metadata-wal-records, old-ui, openmetrics2, otlp-deltatocumulative, otlp-native-delta-ingestion, promql-binop-fill-modifiers, promql-delayed-name-removal, promql-experimental-functions, promql-extended-range-selectors, promql-per-step-stats, search-api, st-storage, st-synthesis, type-and-unit-labels, use-start-timestamps, use-uncached-io, xor2-encoding, zstd-scrape。此外--enable-feature的历史包袱同样由这段 switch 处理auto-reload-config已废弃提示改用--config.auto-reloadpromql-duration-expr、ooo-native-histograms已永久启用no-opnative-histograms提示改用抓取配置项scrape_native_histograms。这些处理逻辑同样位于 cmd/prometheus/main.go。存储层特性Exemplars 存储exemplar-storageOpenMetrics 规范允许抓取目标为某些指标附带 exemplar——指向 MetricSet 之外数据的引用最常见的用途是程序 trace ID。实现上exemplar 存储是一个固定大小的环形缓冲circular buffer在内存中为所有序列保存 exemplar。启用该特性后Prometheus 抓取到的 exemplar 才会被保存。可通过配置文件中 storage/exemplars 区块按“exemplar 数量”控制环形缓冲大小。单个只带trace_idjaeger-trace-id的 exemplar 大约占用 100 字节内存。启用后exemplar 还会被追加写入 WAL 做本地持久化保存时长取决于 WAL 保留期。源码侧该开关直接映射为c.tsdb.EnableExemplarStoragecmd/prometheus/main.go并在配置热重载时被透传给reloadConfig的加载器cmd/prometheus/main.go。关闭时的内存快照memory-snapshot-on-shutdown关闭进程时对内存中的 chunk 连同序列信息做快照并落盘。这样启动时可以直接用该快照恢复内存状态并 m-map 磁盘上的 chunkWAL 回放只需要处理快照之外的 WAL 片段从而显著降低启动时间。延迟 Head 压缩启动delayed-compaction为 Head 压缩的启动时间加上一个不超过 chunk range 10% 的随机偏移帮助同一台宿主机上的多个 Prometheus 实例错开压缩时机、减轻共享资源磁盘、CPU的瞬时压力。约束包括只有自动触发的 Head 压缩及其直接派生的操作会受此延迟影响若连续多次 Head 压缩都可能发生只有第一次会经历延迟延迟期间 Head 照常工作继续提供查询与样本追加延迟只改变压缩开始的时间点产出的 block 时间对齐方式与不延迟时完全一致。绕过页缓存的 IOuse-uncached-io实验性特性仅在 Linux 上可用。启用后 chunk 写入绕过页缓存当前实现为 direct I/O主要目标是消除页缓存行为带来的困惑防止因缓存“虚高”增长导致的内存过量分配。注意该特性在启用时会通过fileutil.UncachedIOSupported()检测平台支持不支持则直接返回错误cmd/prometheus/main.go。元数据 WAL 记录metadata-wal-records启用后Prometheus 将元数据保存在内存中并按序列粒度把元数据变化作为 WAL 记录跟踪。如果你希望通过新版 Remote Write 2.0 发送元数据必须启用此特性。XOR2 chunk 编码xor2-encoding注意此特性开关已废弃。XOR2 float chunk 编码已经稳定应改用配置文件中storage.tsdb段的chunk_encoding.floats字段见 配置文档来显式选择。该开关目前仅把 float chunk 编码的默认值设为xor2在未来大版本中将变为 no-op对应源码中的告警逻辑见 cmd/prometheus/main.go。另外st-storage特性也会自动选择 XOR2 作为默认 float chunk 编码因为 XOR chunk 无法保存 Start Timestamp。Histogram ST chunk 编码histograms-st-encoding警告这是高度实验性且有风险的设置用histogramST和floathistogramST编码的 chunk无法被不支持该编码的旧版 Prometheus 读取。一旦启用并写入数据若回退版本需要手动从磁盘删除这些 block否则所有查询都会报错。编码方案仍在实验中任意版本都可能变化跨版本持久化 block 数据会丢失。编码很新下游工具与 LTS 系统例如 Thanos sidecar 上传的 block可能尚不支持。该设置启用针对原生直方图与 float 直方图样本的新histogramST、floathistogramSTchunk 编码它们在对应直方图 chunk 格式上扩展了 Start TimestampST头与逐样本 ST 编码作用相当于 XOR2 编码 对 float chunk 做的事。该开关不影响 float chunk。st-storage特性会自动启用这些直方图编码若单独启用本开关而未启用st-storage则只使用支持 ST 的直方图 chunk 编码但不会保存摄入时收到的 Start Timestamp。Start TimestampST全家桶Prometheus 围绕“指标样本携带开始时间”提供了一组渐进式特性理解它们的关系是安全启用的前提。ST 零值注入created-timestamp-zero-ingestion说明CreatedTimestamp 特性为保持一致性已更名为 StartTimestamp此特性开关仍沿用旧名以保持稳定性。启用 Start Timestamp 的摄入在合适时 ST 会被注入为值为 0 的样本。目前 Prometheus 支持在PrometheusProto与OpenMetrics1.0.0两种格式上承载 ST其中推荐PrometheusProto——OpenMetrics 1.0 的 ST 信息通过metric_created指标传递解析这类指标既易出错又昂贵增加开销还要小心不要让额外的_created指标污染你的 Prometheus。因此启用created-timestamp-zero-ingestion后Prometheus 会把全局scrape_protocols的默认值改为[PrometheusProto, OpenMetricsText1.0.0, OpenMetricsText0.0.1, PrometheusText0.0.4]即优先协商 Prometheus Protobuf 协议除非显式设置了其他scrape_protocols。从源码看正是把全局默认值替换为config.DefaultProtoFirstScrapeProtocols实现的cmd/prometheus/main.go该协议列表定义在 config/config.go。除了 Prometheus 侧启用被抓取的应用也必须暴露 ST 才能生效。ST 原生存储st-storage启用逐样本的 Start Timestamp 存储贯穿 WAL、TSDB/Agent 与 Remote Write 2.0能够完整保留抓取与接收协议呈现的精确 ST 值。未来该特性将取代通过注入合成 0 样本的created-timestamp-zero-ingestion。目前支持 ST 的格式同样为PrometheusProto与OpenMetrics1.0.0推荐PrometheusProtoST 传递更高效。同样要求被抓取应用暴露 ST。已知限制实验性特性引入新的 WAL 记录类型SamplesV2只能被 Prometheus 3.11 或更高版本回放为了持久化TSDB block该特性会自动为 float 启用 XOR2 chunk 格式、为原生直方图启用 ST chunk 格式与chunk_encoding.floats: xor2和 histograms-st-encoding 开关独立启用时相同。若在配置文件中显式写chunk_encoding.floats: xor且st-storage处于激活状态配置重载时会被拒绝因为 XOR chunk 不保存 Start Timestamp。这些约束在实验阶段结束后可能调整原生直方图与 NHCB 在其他方面的 ST 支持仍在推进中PromQL 层面对 ST 的使用不在本特性范围内见下条use-start-timestamps。源码中该开关同时设置了scrape.ParseST、tsdb.EnableSTStorage、FloatChunkEncoding EncXOR2、EnableHistogramSTEncoding与 agent 端开关并同样切换 proto 优先的抓取协议默认值cmd/prometheus/main.go。ST 在 PromQL 函数中的使用use-start-timestamps启用rate()、irate()、increase()、start_timestamp()等 PromQL 函数对 Start Timestamp 的使用。注意该特性目前不支持扩展范围选择器promql-extended-range-selectors。ST 合成st-synthesis当源端不提供 ST 时对累积型指标Counter、经典直方图、原生直方图合成 Start Timestamp。其思路类似于 OpenTelemetry Collector 社区贡献的 metricstarttimeprocessor 的“减去初始点”策略跟踪前值以检测重置并从第一个样本起减去初始参考点合成一条从零开始的时间线。实验性特性的注意事项特性开启时第一个样本会被丢弃用于建立 ST 参考点。因此若某序列只上报过一个点开启后可能导致该序列没有任何样本入库合成能给出准确的 Start Timestamp 且保持计数器速率准确但原始计数器值将与抓取值不同——第一个点被丢弃、其时间戳被用作后续所有点的起始时间戳后续所有点都会相对该被丢弃的点做归一化减去它。相当于用原始数据创建了一条已知起始时间的新计数器流合成仅对抓取数据生效Remote Write 与 OTLP 接收器尚未实现合成要求样本有序因此没有 ST 的累积样本即使设置了tsdb.out_of_order_time_window也会因乱序被拒绝若某序列的追加失败例如因乱序样本被拒该序列的合成状态会被清除失败后的下一个样本会被当作“第一个样本”再次丢弃以建立新参考点。PromQL 相关特性逐步统计promql-per-step-stats启用后在查询请求中传statsall会返回逐步骤per-step统计包含totalQueryableSamples / totalQueryableSamplesPerStep查询期间加载的样本总数。对rate、sum_over_time这类 range-vector 函数在多步求值时每一步都会计入完整窗口同一点可能在多个步骤被重复计数。samplesRead / samplesReadPerStep样本读取I/O总数。range 查询中的 range-vector 函数只计每步的新增点第 0 步计完整窗口后续步骤只计上一步未出现的点其他查询类型下该值等于 totalQueryableSamples。peakSamples求值期间内存中的峰值样本数用于query.max-samples限制。服务端另有两个可观测计数器prometheus_engine_query_samples_total按步计完整窗口的加载样本数与prometheus_engine_query_samples_read_totalrange-vector 按步计增量读取数。若引擎或查询层面任一未启用该特性逐步骤统计将完全不计算。实验性 PromQL 函数promql-experimental-functions启用被视为实验性的 PromQL 函数。这些函数的名称、语法或语义可能改变甚至可能整体被移除。延迟__name__标签移除promql-delayed-name-removal启用后Prometheus 改变 PromQL 查询结果中移除__name__标签的方式对于需要移除的函数与表达式把移除延迟到查询求值的最后一步而不是每求值一次会派生指标的表达式/函数就移除一次。好处允许通过label_replace、label_join可选地保留__name__避免对__name__标签应用正则匹配器时出现 vector cannot contain metrics with the same labelset 错误。限制与风险分开求值查询的一部分仍会触发 labelset 冲突——手动或用 PromLens 类工具分析中间结果时常见若查询引用了已被移除的__name__标签行为可能改变例如sum by (__name__) (rate({foobar}[5m]))。这类查询很少见且容易修复——上例中去掉by (__name__)在无特性时结果不变在启用特性时则能修复潜在问题理论上可构造聚合到__name__、把“延迟移除”与“未移除”的样本放进同一分组此时该分组的名称会被移除——这种情形在实用查询中几乎不会出现。扩展范围选择器promql-extended-range-selectors为 PromQL 的 range 与 instant 选择器启用实验性anchored与smoothed修饰符让你在rate、increase等函数中更精细地控制 range 边界处理尤其在缺失或不规则数据下。注意原生直方图尚不受扩展范围选择器支持且不支持子查询。anchored在 range 起点使用 lookback delta 内最近的样本若 lookback delta 内无样本则使用 range 内第一个样本range 终点同样使用 range 内最后一个样本。不做外推或插值适合直接获取样本值之间的差。适用于resets、changes、rate、increase、delta。示例increase(http_requests_total[5m] anchored)注意increase配合 anchored 修饰符时返回结果为整数。smoothedrange 选择器在 range 边界处线性插值利用边界前后两侧的样本值做更稳健的估计可抗不规则抓取与缺失样本但它需要求值区间之后的样本才能正确工作见下方规则告警提示。instant 选择器则在求值时间戳处用紧邻前后的两个样本线性插值。适用于rate、increase、delta。示例rate(http_requests_total[step()] smoothed)告警与录制规则注意smoothed需要求值区间之后的样本直接在规则中使用通常会低估结果求值时刻拿不到未来样本。要安全地在规则里用smoothed必须给规则组设置query_offset确保计算窗口完全落在过去、所需样本都已可用。关键告警建议至少偏移一个抓取间隔非关键或希望更强容错容忍漏抓的场景可考虑更大偏移多个抓取间隔。二元运算 fill 修饰符promql-binop-fill-modifiers为 PromQL 二元运算符启用实验性的fill()、fill_left()、fill_right()修饰符允许为二元运算一侧缺失的匹配项填入指定的默认样本值。示例rate(successful_requests[5m]) fill(0) rate(failed_requests[5m])更多细节与示例参见 fill 修饰符文档。抓取与协议相关特性额外抓取指标extra-scrape-metrics注意此特性开关已废弃请改用extra_scrape_metrics配置项可在全局与抓取配置两级设置该开关将在未来大版本移除详见配置文档。启用后每次实例抓取会在以下额外时间序列中存储一个样本scrape_timeout_seconds该目标的scrape_timeout配置值配合scrape_duration_seconds / scrape_timeout_seconds可观察各目标距超时的余量scrape_sample_limit该目标的sample_limit配置值配合scrape_samples_post_metric_relabeling / scrape_sample_limit观察距限制的余量。注意未配置限制时该值为 0上述查询会出现除以 0 得到Inf若只想查“配置了限制”的目标用scrape_samples_post_metric_relabeling / (scrape_sample_limit 0)scrape_body_size_bytes最近一次成功抓取响应的解压后大小。因超出body_size_limit而失败的抓取报-1其他抓取失败报0。Zstandard 抓取压缩zstd-scrape启用后Prometheus 除了 gzip 之外还会在抓取请求中宣告支持 Zstandard 压缩的响应。解压后的响应仍受配置的body_size_limit约束。OpenMetrics 2.0openmetrics2启用对暴露 OpenMetrics 2.0 文本格式的抓取目标的支持内容类型为application/openmetrics-text; version2.0.0。OpenMetrics 2.0 支持仍是实验性的解析器尚未稳定今天 Prometheus 接受的暴露格式未来版本可能拒绝请勿在生产中依赖当前行为。关闭该开关时OpenMetrics 2.0 内容类型会被当作不支持的内容类型处理若目标配置了fallback_scrape_protocol则回退使用它否则抓取失败。如果你正在实现 OpenMetrics 2.0 exporter 或客户端库请注意被 Prometheus 成功抓取不等于你的输出符合规范请以官方 OpenMetrics 2.0 迁移指南为准。类型与单位标签type-and-unit-labels启用后Prometheus 会按 PROM-39 提案的设计开始注入额外的保留标签__type__与__unit__。这些标签来源于既有抓取与摄入格式OpenMetrics Text、Prometheus Text、Prometheus Proto、Remote Write 2、OTLP的元数据结构用户提供的同名__type__、__unit__标签会被覆盖。PromQL 层会以与__name__相同的方式处理这些标签例如在-、等运算中被丢弃并受promql-delayed-name-removal特性影响。该特性让重要元数据信息可以直接随样本与 PromQL 层使用尤其适合想按类型或单位选择指标的用户想处理同名不同类型/单位序列的场景例如原生直方图迁移、或来自 OTLP 端点未经翻译的 OpenTelemetry 指标。后续还有依赖此特性的规划工作例如在类型误用时提供帮助的 PromQL 体验改进、自动重命名、delta 类型等。与元数据记录的行为启用本特性且存在元数据 WAL 记录时若两者给出的 type 或 unit 不一致小概率情况Prometheus 输出倾向于__type__/__unit__标签的值。例如 Remote Write 2.0 场景下即使元数据记录可能因 bug说是 counter只要__type__gauge远端时间序列会被设为 gauge。OTLP 相关特性OTLP delta 转累积otlp-deltatocumulative启用后Prometheus 不再丢弃 delta 时序temporality的 OTLP 指标而是把它们转换为等价的累积形式。不能与otlp-native-delta-ingestion同时启用启动时会报错见前文互斥校验。该转换复用 OTel Collector 的 deltatocumulative 处理器默认设置。delta 转换需要在内存中保持按序列聚合 delta 变化的状态Prometheus 重启后该状态丢失累积序列会从零重新聚合表现为一次计数器重置。该状态会周期性清除不活跃的序列按max_stale设置。启用后可能对性能产生负面影响因为内存状态由互斥锁保护纯累积的 OTLP 请求不受影响。OTLP 原生 delta 支持otlp-native-delta-ingestion启用后允许原生摄入delta 时序的 OTLP 指标原样存储原始样本值不做转换。不能与otlp-deltatocumulative同时启用。当前StartTimeUnixNano字段被忽略delta 指标被赋予“未知”的指标元数据类型。delta 支持处于非常早期阶段摄入与查询流程未来可能变化参见 prometheus/proposals 中第 48 号提案。查询建议标准 PromQL 计数器函数rate()、increase()面向累积指标设计用于 delta 指标会给出错误结果。目前要获得类似效果请用sum_over_time()sum_over_time(delta_metric[range])在指定时间范围内对 delta 值求和sum_over_time(delta_metric[range]) / range计算 delta 指标按秒速率。若range不是指标采集间隔的整数倍上述写法可能不理想。例如指标采集间隔为 10m而你执行sum_over_time(delta_metric[1m]) / 1m1m step的 range 查询图表会每 10 分钟出现一个高速率单点而不是 10 个点上的较低恒定值。当前已知坑delta 指标若通过federation暴露当摄入间隔与联邦端点的抓取间隔不一致时数据可能被错误采集难以判断某指标是 delta 还是累积时序——指标名与标签中没有时序提示。目前若同时摄入 delta 与累积指标建议显式添加自定义标签加以区分。未来计划引入类型标签来一致地区分指标类型并可能让 PromQL 函数类型感知例如对 delta 指标使用仅适用于累积的函数时给出警告同一时间戳摄入多个样本时只保留其中一个点样本不会求和这是 Prometheus 的通用行为——相同时间戳的重复样本会被拒绝。任何聚合都必须在发送样本到 Prometheus 之前完成。规则引擎与 API/UI 特性独立规则并发求值concurrent-rule-eval默认情况下规则组之间并发执行但组内规则串行执行——因为规则可能把前一条规则的输出作为自己的输入。若规则间没有可检测的依赖关系就没有必要串行运行。启用concurrent-rule-eval后规则组内不依赖其他规则的规则会并发求值可能改善规则组求值延迟与资源利用率代价是增加并发查询负载。并发规则求值数量由--rules.max-concurrent-evals配置默认值为 4见 cmd/prometheus/main.go 的默认值注册设置该值时可能需要同步调整query.max-concurrency。Search APIsearch-api启用实验性的搜索 API 端点支持模糊匹配与过滤地发现指标名、标签名与标签值详见搜索 API 文档。配套的--web.search.max-limit标志默认10000为搜索端点接受的limit查询参数设置硬性上限超限请求返回 HTTP 400默认响应限制100会被静默钳制到该上限因此运维调小上限不会破坏不带limit的请求设为0表示完全禁用上限——不建议在可信网络之外暴露端点时这样做否则单个客户端可一次性请求整个索引。旧版 Web UIold-ui回退到提供旧版Prometheus 2.xWeb UI而不是新 UI。随 Prometheus 3.0 发布的新 UI 是一次完全重写目标是更干净、少干扰、内部实现更现代但功能尚不完全、也未充分经生产检验部分用户仍可能偏好旧 UI。启用与验证的实操清单启用启动命令追加--enable-featurename1,name2注意st-storage会连带启用 XOR2 与直方图 ST 编码并与created-timestamp-zero-ingestion一样把默认scrape_protocols切换为 proto 优先列表config/config.go。核对日志启动时每个开关都会输出对应的 Info/Warn 日志如 Experimental in-memory exemplar storage enabled废弃选项extra-scrape-metrics、xor2-encoding等会输出明确的迁移告警未知名称只有 Warn。验证运行态访问GET /api/v1/features按类别查看构建支持的特性与启用状态该端点的回归行为由 cmd/prometheus/features_test.go 的TestFeaturesAPI测试保障。迁移提示extra-scrape-metrics→ 配置项extra_scrape_metricsxor2-encoding→ 配置项storage.tsdb.chunk_encoding.floats: xor2auto-reload-config→ 命令行--config.auto-reload。迁移后应移除这些开关避免未来大版本中行为变化。【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考