Prometheus remote_read 配置：读取路径、验证与常见误区

Prometheus remote_read 用于从另一台 Prometheus 或兼容存储读取时序数据，再交给本机的 PromQL 引擎计算。它发生在查询路径上；remote_write 则把本机接收的样本持续发送给外部接收端，两者的方向和用途不同。

先说观测云的边界。2026 年 10 月 27 日复核的观测云、TrueWatch 公开文档，说明了 DataKit 的 /prom_remote_write 接收端，以及产品内的 DQL、PromQL 查询，但没有明确提供可供外部 Prometheus 使用的 Remote Read URL、认证与兼容约定。这是当前资料不足，不能据此断言所有部署均不支持。不要把 /prom_remote_write 或 DataKit 的 /v1/query/raw 填进 remote_read.url。

本文介绍从另一台 Prometheus 或明确支持 Remote Read 的存储读取数据。如果目的是把指标发送到观测云，请使用后文的 Remote Write 路径。示例已对照官方配置文档复核，但本轮没有执行特定版本组合的完整传输、认证和回滚测试。

Remote Read 读取什么

Prometheus 根据标签匹配条件和时间范围向远端请求原始时序，再在本地执行聚合、rate、连接等 PromQL 运算。它不会把任意 PromQL 表达式交给远端分布式执行。因此，某个系统有 /api/v1/query，并不等于它兼容 Remote Read。

常见用途包括：查询超出本地留存期的历史指标；迁移期间从旧 Prometheus 读取数据；通过 adapter 把其他存储转换为 Remote Read 协议。查询返回了样本，并不意味着样本已经回填本地 TSDB、完成数据复制，或自动进入观测云。

想从第三方存储读数据，查该产品的 Remote Read 文档；想把 Prometheus 指标存入观测云，配置 DataKit Remote Write；想从观测云读回指标，则应先取得适用部署的产品接口资料，不能猜 URL。

读路径与写路径分开验证

用户请求本机 PromQL API，本机取得远端原始时序后计算结果。发送到观测云时，则由 Prometheus 将采集的样本通过 remote_write 交给 DataKit，再上报工作空间。

同一台 Prometheus 可以同时配置两者，但不能假定 Remote Read 返回的数据会自动经 Remote Write 复制。采集、查询、recording rule 和外发应分别验证。

文档复核确认了哪些内容

本轮确认了 remote_read 配置项和默认值、/api/v1/read 协议接口、DataKit 写入与 DQL 查询接口，以及产品内的 PromQL 模式；没有确认观测云面向外部提供的 Remote Read 接口约定，也没有运行读者实际使用的二进制组合。

Prometheus 明确把 Remote Read 列为非稳定 API，即使非大版本更新也可能变化。记录查询端、存储或 adapter 的准确版本、响应类型、认证和限制，比一句“兼容 Prometheus”更有意义。

用于生产前，还需要验证真实请求、认证、数据结果、超时和回滚。资料审核不能代替这些环境测试。

先确认 endpoint 的约定

从远端产品或 adapter 的官方资料确认：

• 明确的 Remote Read URL；Prometheus 自身使用 /api/v1/read。
• Snappy 压缩的 Protocol Buffers 请求及兼容响应。
• SAMPLES、STREAMED_XOR_CHUNKS 等响应类型的支持情况。
• TLS、认证、租户 Header、证书 server name。
• 留存、最大查询范围、series/sample 数、超时和速率限制。
• Native histogram、stale marker、external label 的处理。

浏览器打开 URL 返回错误或 HTTP 200，都不能说明兼容性。Remote Read 以 POST 发送二进制 Protocol Buffers 请求，不是手写 JSON 的 PromQL API。

第一次测试，建议准备已有已知指标的 source Prometheus，再用另一台不采集相同序列的 query Prometheus 发起读取。先限定一个指标、一个 job、约五分钟数据。

最小配置

下面的 DNS 仅作示例，须替换为实际内部地址。源端应已保存测试时间内的 up{job="prometheus"}，查询端不应同时本地采集该序列。

global:
  scrape_interval: 30s

remote_read:
  - name: "jp_archive_validation"
    url: "http://prometheus-archive.monitoring.svc:9090/api/v1/read"
    remote_timeout: 30s
    read_recent: true
    filter_external_labels: false

name 用于在指标和日志中区分配置。remote_timeout 默认 1m，这里用 30s 限定隔离测试的等待时间；生产值应依据序列数量、延迟和远端限制确定，不能只靠不断延长超时解决问题。

read_recent: true 让这个测试读取近期远端数据。生产环境如果由本地覆盖近期、远端覆盖历史，默认的 false 可能更合适。

filter_external_labels: false 暂时排除查询端附加 external label 的筛选影响。它不是租户隔离或安全建议；生产配置仍需核对标签约定。

用文件引用凭据，验证 TLS

Remote Read 可使用 Prometheus 通用 HTTP 客户端设置。跨网络访问时，应配置合适的认证和证书验证，不把秘密直接写入正文或关闭 TLS 校验。

remote_read:
  - name: "jp_archive_secure"
    url: "https://prometheus-archive.internal.example/api/v1/read"
    remote_timeout: 30s
    read_recent: false
    filter_external_labels: false
    authorization:
      type: "Bearer"
      credentials_file: "/etc/prometheus/secrets/remote-read.token"
    tls_config:
      ca_file: "/etc/prometheus/tls/remote-read-ca.crt"
      server_name: "prometheus-archive.internal.example"
      min_version: "TLS12"

限制凭据和私钥文件的读取权限，避免进入未受控备份、支持包和配置导出。不要长期使用 insecure_skip_verify: true。根据接收端能力采用 authorization、basic_auth、oauth2 或双向 TLS，并在支持时使用凭据文件。

查询本身也可能耗尽资源。还需要网络控制、TLS、认证和适当的权限设计。required_matchers 是客户端路由条件，不是远端的访问授权。

校验配置后再重载

使用与运行中 Prometheus 相同版本的 promtool：

promtool check config /etc/prometheus/prometheus.yml

通过检查只能确认工具覆盖的配置有效性，不能证明 DNS、认证、协议、数据或性能正常。失败时先修正配置，不要重载。

已有部署开启 --web.enable-lifecycle 时，可向 /-/reload 发 POST 或 PUT：

curl --fail --silent --show-error -X POST \
  http://127.0.0.1:9090/-/reload

curl --fail --silent --show-error \
  http://127.0.0.1:9090/-/ready

未开启时沿用现有 SIGHUP、Operator、服务管理器或滚动更新流程，不要为了方便重载而扩大公开访问范围。ready 只表示可以提供服务，并未验证 Remote Read 数据路径。

从正常 PromQL API 验证结果

向 query Prometheus 发查询，不要自行拼 JSON 调用 /api/v1/read。把示例日期改为源端确实保存该指标的五分钟区间：

curl --fail --silent --show-error --get \
  'http://127.0.0.1:9090/api/v1/query_range' \
  --data-urlencode 'query=up{job="prometheus"}' \
  --data-urlencode 'start=2026-08-01T00:00:00Z' \
  --data-urlencode 'end=2026-08-01T00:05:00Z' \
  --data-urlencode 'step=30s' \
  --data-urlencode 'timeout=25s'

成功的 range query 返回 matrix。下方只展示缩减后的响应形状，不是本轮实测结果：

{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": {
          "__name__": "up",
          "job": "prometheus"
        },
        "values": [
          [1785542400, "1"]
        ]
      }
    ]
  }
}

status: "success" 也可能对应空 result，因此还要确认：

1. 查询端没有本地采集目标序列，结果确实依赖远端。
2. 同一表达式和时间窗口在源端可返回数据，名称、预期标签、时间戳和值可对照；考虑 external label 的转换。
3. 结果至少包含一条预期序列和样本。
4. 仅在隔离环境，把远端 URL 改成故意无效的地址或阻断测试连接，远端独有的查询应失败或变空。
5. 分享证据前去掉租户标识、秘密和内部 URL。

如果本地也有同一序列，查询成功可能掩盖远端故障。使用不同 instance 或历史窗口来隔离；不要为做对照试验故意切断生产链路。

空结果、缺样本和超时如何排查

Remote Read 协议时间戳使用毫秒；PromQL HTTP API 接受 RFC3339 或 Unix 时间戳。不要混淆界面的本地时区与请求中的 UTC。Remote Read 不会补出原本不存在的样本，也不会把失败的 scrape 变成成功。

网络排查要区分 DNS、TLS 握手、代理、Service Mesh 和 NetworkPolicy。TCP 连通不能证明协议兼容，最终仍以真实 Prometheus 查询及预期样本为准。

三个容易造成误判的设置

read_recent 默认 false，决定是否读取本地应完整覆盖的时间段。对全部重叠范围都请求远端，会增加延迟和负载，应明确划分本地与远端职责。

filter_external_labels 默认 true。查询端可能把自己的 external label 作为额外完全匹配条件发出，再从返回结果中移除自己附加的标签。提供 /api/v1/read 的源 Prometheus 也会在响应时附加自己的 external label，并不把它们写入本地 TSDB。因此，直接向源端执行 PromQL 与 Remote Read 返回的标签集不一定完全相同；双方标签不匹配还可能筛掉全部数据。

required_matchers 只有在 selector 包含指定完全匹配条件时才选择该 endpoint。仅当远端序列确实有 archive="jp-prod" 时，才使用以下示例：

remote_read:
  - name: "jp_prod_archive"
    url: "https://prometheus-archive.internal.example/api/v1/read"
    required_matchers:
      archive: "jp-prod"

http_requests_total{archive="jp-prod",job="api"} 可以选中它，http_requests_total{job="api"} 不会。使用稳定低基数标签，不要用用户或请求 ID。这个条件不提供授权。

先收窄查询，再考虑延长超时

查询端要接收并处理原始数据。{__name__=~".+"} 这类宽 selector，加上长时间范围和高基数标签，会同时消耗存储、网络、CPU 和内存。流式响应并不让无限查询变安全。

先选一个指标，用 job、cluster、service 缩小序列；再从五分钟扩到一小时、六小时，记录 series/sample 数、响应大小、远端延迟及查询端资源。逐条复现实际仪表板、告警和 recording rule 表达式，检查超时反馈与重试是否放大负载。

remote_timeout、查询 API 的 timeout、服务端 query timeout、反向代理及远端存储限制互相独立，最短的有效期限先触发。只延长其中一项，无法解决过宽的 selector。

把指标写入观测云也应避免无限增长的 user_id、请求 ID、完整 URL 标签，但存储设计与 Remote Read 性能仍是两项独立评估。

兼容性要精确到版本

Remote Read 通过 HTTP 发送 Snappy 压缩的 Protocol Buffers 请求，Prometheus 的接口是 /api/v1/read。官方定义了样本和流式 chunk 响应；流式方式把大响应拆成 frame，双方需要支持协商的响应类型。

记录客户端、存储或 adapter 的准确 build，以及 URL、TLS、认证、租户路由；确认 SAMPLES、STREAMED_XOR_CHUNKS、浮点样本、native histogram、stale marker 和各类 frame/series/sample/时间范围/并发限制。失败时保留脱敏后的 HTTP 状态和双方日志。

升级后至少重测一个浮点指标、实际使用的 histogram、缺失区间和超时场景。“支持 Prometheus 3”或“支持 PromQL”不足以证明这些细节。

指标发送到观测云，使用 Remote Write

启用 DataKit Prometheus Remote Write 采集器，在 Prometheus 配置发送方向：

remote_write:
  - url: "http://datakit.monitoring.svc:9529/prom_remote_write"

从 sample 复制并管理 prom_remote_write.conf，确认 path = "/prom_remote_write"。限制网络入口，评估 TLS 终止、认证、指标过滤和标签。文档提供 Basic Auth 配置，但不要把真实凭据贴进文章或工单。

指标分析中的 PromQL 查询产品已存储的指标，不等于对外提供 Remote Read 服务。评估时固定 job_as_measurement、measurement_name、keep_exist_metric_name 和标签过滤/重命名设置，比较写入前后的指标名与真实查询结果。接收端 HTTP 2xx 不能证明原仪表板和告警仍然等价。

只回滚本次读配置

把 Remote Read 变更与其他操作分开：

1. 保存原配置、版本、endpoint、凭据文件引用和 external label。
2. 只移除目标 remote_read 条目，或恢复它的旧值。
3. 执行 promtool check config /etc/prometheus/prometheus.yml。
4. 按现有流程重载或滚动更新。
5. 检查 /-/ready、已知本地查询和告警。
6. 确认远端独有的对照查询不再通过该条目返回数据。
7. 按规范清理测试凭据、临时网络例外和调试日志。

移除 Remote Read 不会删除远端原数据；此前的查询也未把数据永久迁入本地。如果同时使用观测云 Remote Write，不要把它一并删掉，除非独立变更方案要求如此。

生产采用前的判断

评估窗口应覆盖代表性的仪表板、告警和临时查询。至少要有版本兼容依据、预期样本和标签结果、三个关键选项的采用理由、故障和超时行为、真实基数下可接受的负载、凭据/TLS 轮换与租户边界验证，以及成功回滚记录。Remote Write 并行使用时，另测命名、外发量和查询。

看到一条序列、HTTP 200 或表达式合法，都不足以通过验收。Remote Read 给查询可用性增加了远端依赖，它的故障也可能影响仪表板和告警计算。

尚需证据的问题分别是什么

协议方向、默认值和本地 PromQL 计算已有文档依据。其他条件应分类处理，不能统称“文章未确认”：

• 产品资料：本轮公开文档没有明确观测云 Remote Read endpoint、协议、认证、租户和限制；实现前需取得相应接口约定。
• 部署测试：实际版本组合、native histogram、流式 chunk、stale marker、基数、留存、延迟、超时，以及告警/规则/仪表板等价性，需要在具体环境验证。
• 客户条款：SLA、存储、处理和备份地点以适用合同为准，endpoint 地域名或查询成功不能证明数据驻留。

本文不承诺全版本兼容、无限查询、无损迁移或零停机。这些结论需要超出资料审核范围的证据。

官方资料

配置与协议于 2026 年 10 月 27 日复核：

1. Prometheus Storage；术语表：读写方向、原始序列与本地计算。
2. 配置参考：Remote Read 默认值与 HTTP/TLS 设置。
3. Remote Read API：接口稳定性、响应类型与 external label。
4. HTTP API：range query、时间戳、返回结构。
5. Management API；promtool：配置检查与重载。
6. 安全模型；Remote Read 流式设计：暴露边界、查询负载和协议设计。
7. TrueWatch Remote Write；观测云 Remote Write：接收配置、指标名和标签。
8. TrueWatch Metrics；Metrics Analysis：产品内指标与 PromQL。
9. DataKit HTTP API：DQL 工作空间查询及其与 Remote Read 的区别。