Prometheus remote_storage_adapter 详解：自建 Graphite、OpenTSDB、InfluxDB 的 Remote Write/Read 适配器

Prometheus remote_storage_adapter 详解自建 Graphite、OpenTSDB、InfluxDB 的 Remote Write/Read 适配器【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus本文基于 README 讲解 Prometheus 官方示例中的 remote_storage_adapter一个通过 remote write 协议接收样本并写入 Graphite、OpenTSDB、InfluxDB 的写适配器同时还是支持 remote read 协议从 InfluxDB 回读数据的读适配器。读完本文你将掌握该适配器的构建与启动方法、全部命令行参数、prometheus.yml的对接配置以及三个存储后端各自的标签映射、转义规则与查询转换等源码级实现细节。背景为什么需要一个独立适配器Prometheus 曾内置 Graphite、OpenTSDB、InfluxDB 等 remote storage 实现这些实现后来从 Prometheus 主程序中被移除。README 明确指出remote_storage_adapter 就是为这些被移除的实现提供替代方案而存在的写适配器全部三种存储以 HTTP 服务形式接收 Prometheus remote write 协议发来的样本再转发到 Graphite、OpenTSDB 或 InfluxDB可以一次配置多个目标并行写入读适配器目前仅 InfluxDB实现 remote read 协议的/read端点把 Prometheus 的读请求翻译成 InfluxDB 查询并回传时序数据。从源码结构看这个适配器位于documentation/examples/remote_storage/remote_storage_adapter/目录下按存储后端拆成三个子包graphite、opentsdb、influxdb由 main.go 统一装配。它属于 documentation/examples/remote_storage 下的独立 Go module与 Prometheus 主 module 分离依赖版本互不影响。构建进入适配器目录后直接构建即可该目录归属于documentation/examples/remote_storage这个独立 Go modulecd documentation/examples/remote_storage/remote_storage_adapter go build构建产物为同名可执行文件remote_storage_adapter。运行三种存储的启动示例README 给出的三种典型启动命令分别如下。Graphite走 TCP 明文协议默认端口由你的 Graphite 服务端决定./remote_storage_adapter --graphite-addresslocalhost:8080OpenTSDB走 HTTP API./remote_storage_adapter --opentsdb-urlhttp://localhost:8081/InfluxDB同时启用写与读认证 token 通过环境变量传入INFLUXDB_AUTH_TOKENtoken ./remote_storage_adapter --influxdb-urlhttp://localhost:8086/ --influxdb.organizationorganization_name --influxdb.bucketbucket_name执行./remote_storage_adapter -h可查看全部 flag。结合 main.go 的 parseFlags完整参数如下表默认值均取自源码Flag默认值说明--graphite-address空Graphite 服务的host:port为空则不启用 Graphite 写入--graphite-transporttcp与 Graphite 通信的传输协议net.Dial语义即tcp--graphite-prefix空写入 Graphite 时给所有指标路径加的前缀--opentsdb-url空OpenTSDB 服务 URL为空则不启用--influxdb-url空InfluxDB 服务 URL为空则不启用--influxdb.bucket空InfluxDB 的 bucket2.x 概念--influxdb.organization空InfluxDB 的 organizationINFLUXDB_AUTH_TOKEN环境变量空InfluxDB 认证 token注意它不是命令行 flag而是 在 parseFlags 中从环境变量读取--send-timeout30s向各 remote storage 发送样本的超时时间--web.listen-address:9201HTTP 服务监听地址/write、/read、/metrics都挂在这里--web.telemetry-path/metrics适配器自身指标暴露路径此外还可通过flag.AddFlags注册的一组--log.level/--log.format参数调整日志基于promslog。buildClients的逻辑main.go值得注意配置了哪个后端就实例化哪个 writer三者可以任意组合、同时启用同一批样本会被并行写入所有已配置的存储。InfluxDB 客户端特殊之处是它同时实现了writer和reader两个接口所以启用 InfluxDB 后/read端点才可用。配置 Prometheus 对接适配器README 给出的prometheus.yml片段如下地址对应适配器默认的:9201监听端口# Remote write configuration (for Graphite, OpenTSDB, or InfluxDB). remote_write: - url: http://localhost:9201/write # Remote read configuration (for InfluxDB only at the moment). remote_read: - url: http://localhost:9201/read要点remote_write指向适配器的/writeGraphite、OpenTSDB、InfluxDB 均可用remote_read指向/read当前仅支持 InfluxDB。从 main.go 的 /read 处理逻辑 可以看到源码中明确写了TODO: Support reading from more than one reader and merging the results即 reader 数量必须恰好为 1否则直接返回 500。所以remote_read只应在只配置了 InfluxDB 的场景下启用。写链路/write 端点的实现Prometheus 的 remote write 客户端把prompb.WriteRequest做 protobuf 序列化、snappy 压缩后 POST 到url。适配器侧的处理在 main.go 的 serve 函数解码请求调用 storage/remote/codec.go 的 DecodeWriteRequest该函数注释明确写着 Used also by documentation/examples/remote_storage完成 snappy 解压 protobuf 反序列化得到prompb.WriteRequest转换为内部样本protoToSamples把每条TimeSeries的 labels 还原为model.Metric样本时间戳为毫秒并行分发为每个 writer 起一个 goroutine 并发写入sync.WaitGroup等全部完成后才响应 Prometheus避免 remote write 队列在写慢时过早释放数据埋点每次分发记录received_samples_total总接收量、sent_samples_total{remote}按后端计成功发送量、failed_samples_total{remote}失败量与sent_batch_duration_seconds{remote}批量发送耗时全部暴露在--web.telemetry-path默认/metrics下可用于对适配器自身做监控告警。三种后端的数据映射与限制Graphite标签折叠进指标路径Graphite 没有标签概念graphite/client.go 的pathFromMetric把标签“压”进点分路径prefix.指标名.标签名.标签值...标签按字典序排序保证同一条 series 路径稳定。写入采用 Graphite 的 plain-text 行协议路径 值 时间戳经 TCP 直连--graphite-transport指定默认tcp一次性发送。由于 Graphite 对合法字符的限制很严escape.go 实现了一套近似百分号编码的转义.、%、/、一律百分号编码(){},.\前加反斜杠其余可打印字符原样保留非标打印字节统一转%XX。例如http://example.org:8080会变成http:%2F%2Fexample%2Eorg:8080。该编码保证任意标签值都能落进 Graphite 文件名whisper 后端以文件名存数据。相关行为有 escape 测试 与 client_test.go 覆盖。注意 client.go 会静默跳过 NaN/±Inf 样本并打 debug 日志。OpenTSDBJSON put API 与下划线转义opentsdb/client.go 把整批样本序列化为 JSON 数组POST 到 OpenTSDB 的/api/put端点Content-Type: application/json带--send-timeout超时控制。指标名成为 OpenTSDB 的 metric其余标签一一映射为 tags。成功时 API 返回 204失败返回 400响应体是{failed: n, success: m}形式的统计适配器据此报错。与 Graphite 同理OpenTSDB 字符串只允许[a-zA-Z0-9._/-]tagvalue.go 因此定义了TagValue类型并实现自定义MarshalJSON/UnmarshalJSON下划线_转义为__冒号:转义为_.因为 Prometheus 指标名常含:其余非法字节转_XX十六进制。例如指标http_request_duration_seconds_bucket会变成http__request__duration__seconds__bucket。tagvalue_test.go 对编解码往返做了测试。OpenTSDB 客户端同样跳过 NaN/±Inf 样本。InfluxDB写为 Line Protocol Point读为 Flux 查询influxdb/client.go 基于官方influxdb-client-go/v2面向 InfluxDB 2.xorganization bucket 模型写入Write指标名映射为 measurement其余标签映射为 tags样本值放入 fieldvalue时间精度设为毫秒influx.DefaultOptions().SetPrecision(time.Millisecond)通过WriteAPIBlocking逐点写入并开启批处理默认批大小 5000后Flush。被跳过NaN/±Inf的样本会体现在客户端自行注册到/metrics的prometheus_influxdb_ignored_samples_total计数器上见 main.go 对 InfluxDB 客户端MustRegister的处理。读取ReadPrometheus remote read 请求里的prompb.Query携带标签 matcher 和时间范围buildCommand将其翻译成 Flux 管道from(bucket: …) | range(start:…, stop:…) | filter(...)matcher 映射规则为Prometheus matcherFlux 条件适用对象r.x v指标名 / 普通标签!r.x ! v普通标签~r.x ~ /re/指标名 / 普通标签!~r.x !~ /re/普通标签注意一个源码中明确的限制!~正则不等于matcher 用于指标名时会直接报错 non-equal or regex-non-equal matchers are not supported on the metric name yetclient.go。结果侧mergeResult把 Flux 记录转回prompb.TimeSeriesmeasurement 还原为__name__标签、tags 还原为标签对并过滤掉_time、_value、_measurement等 Flux 内置字段当查询选中不同标签集合的 series 时InfluxDB 会对所有 series 返回全量标签名缺失的为空值代码用“空标签值等价于不存在的标签”这一约定跳过空值再按时间戳归并去重最终包成 snappy 压缩、Content-Type: application/x-protobuf的ReadResponse返回main.go。小结与适用边界remote_storage_adapter 是“协议翻译器”它对 Prometheus 暴露标准 remote write/read HTTP 接口对后端使用各存储的原生协议Graphite plain text / OpenTSDB HTTP put / InfluxDB client API部署上与 Prometheus 解耦可按需独立扩容与重启能力边界由源码直接决定写端点支持多后端并行读端点当前仅支持 InfluxDB 且 reader 必须唯一非有限浮点值NaN/±Inf在三种后端中都会被丢弃其中 InfluxDB 有独立计数器可观测相关行为均有测试覆盖graphite/client_test.go、opentsdb/client_test.go、opentsdb/tagvalue_test.go、influxdb/client_test.go可作为二次开发时的行为参照。【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考