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 變更

把 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 的區別。