企业官网建设流程全解析

Prometheus 如何用 st-storage 特性持久化保存起始时间戳

【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus

如果你的应用或 exporter 在抓取时携带了起始时间戳（Start Timestamp，ST），而你不希望 Prometheus 只把它注入为 0 值合成样本，可以把st-storage特性打开：它让 Prometheus 按样本保存精确的 ST 值，并经由 WAL、TSDB/Agent 以及 Remote Write 2.0 持久化和外发。本文基于 Prometheus 仓库内的docs/feature_flags.md、docs/configuration/configuration.md和docs/command-line/prometheus.md，给出启用该特性的完整路径：启动参数、配置约束、验证方式，以及文档明确列出的限制。

了解 st-storage 做什么

st-storage是一个实验性 feature flag，通过--enable-feature=st-storage启用（见 feature flags 文档）。启用后：

• Prometheus 为每个样本保存起始时间戳，保留抓取/接收协议中呈现的精确 ST 值，而不是像created-timestamp-zero-ingestion那样注入合成的 0 值样本。文档说明未来它打算替代后者的注入行为。
• ST 的保存贯穿 WAL、TSDB/Agent 以及 Remote Write 2.0 三条路径。

当前支持携带 ST 的协议是PrometheusProto和OpenMetrics1.0.0，文档推荐PrometheusProto（ST 传递更高效）。OpenMetrics 1.0 的 ST 信息以<metric>_created指标形式共享，解析易错且开销大，还需注意不要污染出额外的_created指标。

启用特性的启动方式

在启动 prometheus 时通过逗号分隔的--enable-feature参数启用：

./prometheus \ --config.file=prometheus.yml \ --enable-feature=st-storage

该参数在 命令行文档 中有完整参数列表，st-storage是其中的合法选项之一；多个特性用逗号分隔。

启动后源码会执行一系列内部动作（见 cmd/prometheus/main.go）：设置ParseST与EnableSTStorage，把 float chunk 编码设为 XOR2，开启 ST 兼容的直方图 chunk 编码，并把全局默认scrape_protocols改为优先协商 Prometheus Protobuf 协议（除非你在配置里显式设置了不同的scrape_protocols）。启动日志中会出现类似下面的提示（文档未给出固定日志原文，此处仅为说明该行为会体现在日志中）：

Experimental start timestamp storage enabled. XOR2 and ST-capable histogram chunk encodings enabled. ... Changed default scrape_protocols to prefer PrometheusProto format.

一个重要前提来自 feature flags 文档：除了启用该特性，被抓取的应用本身必须暴露起始时间戳。只开 flag 而数据源不携带 ST，存储链路也不会产生 ST 数据。

配置约束：float chunk 编码必须与 st-storage 兼容

持久化到 TSDB 块的前提是 float chunk 使用 XOR2 编码，因为 XOR chunk 不保存起始时间戳。配置文档中storage.tsdb.chunk_encoding.floats字段说明：

• 该字段缺省时：如果设置了--enable-feature=xor2-encoding或--enable-feature=st-storage，编码为xor2；否则为xor。
• 在st-storage激活期间显式把chunk_encoding.floats设为xor是不兼容的：Prometheus 会在启动或配置 reload 时拒绝该配置。
• 该字段支持运行时 reload；但在st-storage开启时 XOR 与 XOR2 互不兼容，编码变更后进行中的 chunk 会在下一次 append 时切分，新编码立即生效。

因此实践上的最短路径是：不要在配置文件中显式写chunk_encoding.floats，让st-storage自动选择xor2；如果你曾经显式写过floats: xor，请删除该行，否则启动/reload 会被拒绝。

直方图侧同理：st-storage会自动启用histograms-st-encoding对应的histogramST与floathistogramST编码（见 feature flags 文档）。注意该编码文档标注为高度实验性：老版本 Prometheus 无法读取这些块，一旦写入数据，降级时需要手动从磁盘删除受影响的块，否则所有查询都会报错；下游工具（例如 Thanos sidecar 上传的块）也可能尚不支持。

验证特性是否生效

确认 flag 被正确解析、特性已激活，可以使用/api/v1/features端点（见 API 文档）：

curl http://localhost:9090/api/v1/features

该端点返回各特性分类下各特性的启用状态（布尔值），data中按api、promql等类别分组。文档给出的响应结构示例：

{ "status": "success", "data": { "api": { "admin": false, "exclude_alerts": true }, "prometheus": { "agent_mode": false, "auto_reload_config": false } } }

（以上为文档中的结构示例，实际返回包含全部特性分类与条目。）

如果要进一步确认查询链路能读到 ST，文档给出了start_timestamp()函数（见 PromQL 函数文档）：start_timestamp(v instant-vector)返回向量中每个样本的起始时间戳（自 1970-01-01 UTC 的秒数），同时作用于 float 和 histogram 样本。注意它有两个前提：直接作用于 instant vector，且必须启用use-start-timestampsfeature flag，否则返回空结果。也就是说，端到端验证需要同时启用两个特性：

./prometheus \ --config.file=prometheus.yml \ --enable-feature=st-storage,use-start-timestamps

排查问题与已知限制

以下是 feature flags 文档明确列出的限制，启用前应先确认：

1. WAL 兼容性：st-storage引入新的 WAL 记录类型SamplesV2，只能由 Prometheus 3.11 或更高版本回放。如果你的升级/回滚路径中存在 3.11 之前的实例，需要评估这条 WAL 回放边界。
2. 编码约束：显式设置chunk_encoding.floats: xor与st-storage冲突，配置加载会在 reload 时被拒绝——如果看到启动或 reload 失败，先检查这一项。
3. ST 支持范围：原生直方图和 NHCB 的其余 ST 支持仍在进行中（文档链接了上游 issue #18315）。
4. PromQL 使用 ST 不在本特性范围内：本特性只负责存储；要在查询中使用 ST，需要单独的use-start-timestamps特性。
5. 块编码的降级风险：直方图 ST 编码写入的块，老版本 Prometheus 无法读取，降级时需手动删除磁盘上的受影响块，否则所有查询返回错误。

下一步

• 如果数据源暂时不暴露 ST，但希望为累积型指标（Counter、Classic Histogram、Native Histogram）合成出基于零时间线的 ST，可另行启用st-synthesis特性（见 feature flags 文档），它会检测重置并从首个样本合成时间戳。
• 如果需要向远端系统外发精确 ST，确认 remote write 使用 2.0 协议；CHANGELOG 中记录了 remote write V2 转发 histogram 起始时间戳的相关增强。
• 特性行为属于实验性，后续版本可能变化，变化会通过 release changelog 通告（见 CHANGELOG）。

【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus