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

Prometheus 如何用 st-storage 特性持久化保存起始时间戳【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus如果你的应用或 exporter 在抓取时携带了起始时间戳Start TimestampST而你不希望 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-featurest-storage启用见 feature flags 文档。启用后Prometheus 为每个样本保存起始时间戳保留抓取/接收协议中呈现的精确 ST 值而不是像created-timestamp-zero-ingestion那样注入合成的 0 值样本。文档说明未来它打算替代后者的注入行为。ST 的保存贯穿 WAL、TSDB/Agent 以及 Remote Write 2.0 三条路径。当前支持携带 ST 的协议是PrometheusProto和OpenMetrics1.0.0文档推荐PrometheusProtoST 传递更高效。OpenMetrics 1.0 的 ST 信息以metric_created指标形式共享解析易错且开销大还需注意不要污染出额外的_created指标。启用特性的启动方式在启动 prometheus 时通过逗号分隔的--enable-feature参数启用./prometheus \ --config.fileprometheus.yml \ --enable-featurest-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-featurexor2-encoding或--enable-featurest-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.fileprometheus.yml \ --enable-featurest-storage,use-start-timestamps排查问题与已知限制以下是 feature flags 文档明确列出的限制启用前应先确认WAL 兼容性st-storage引入新的 WAL 记录类型SamplesV2只能由 Prometheus 3.11 或更高版本回放。如果你的升级/回滚路径中存在 3.11 之前的实例需要评估这条 WAL 回放边界。编码约束显式设置chunk_encoding.floats: xor与st-storage冲突配置加载会在 reload 时被拒绝——如果看到启动或 reload 失败先检查这一项。ST 支持范围原生直方图和 NHCB 的其余 ST 支持仍在进行中文档链接了上游 issue #18315。PromQL 使用 ST 不在本特性范围内本特性只负责存储要在查询中使用 ST需要单独的use-start-timestamps特性。块编码的降级风险直方图 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考