Prometheus remote_read設定ガイド：仕組み・検証・Guanceとの境界

prometheus remote_readは、Prometheusが別のPrometheusや互換性のある長期保存システムから時系列を読み、通常のPromQLクエリへ透過的に組み込む機能です。データを外部へ送るremote_writeとは方向も責任も異なります。

先にGuanceとの境界を明確にします。2026年8月1日に確認したGuance / TrueWatchの公開一次資料では、DataKitがPrometheus Remote Writeを/prom_remote_writeで受信する構成と、Guance / TrueWatch内でDQLやPromQLを使う方法は確認できました。しかし、Prometheusのremote_read.urlに指定できる、Guance管理のRemote Read互換endpointは確認できませんでした。したがって、DataKitの/prom_remote_writeや/v1/query/rawをremote_readのURLとして設定してはいけません。

本稿は、第三者のRemote Read対応ストレージまたは別のPrometheusから読み取るための実装ガイドです。GuanceへPrometheusメトリクスを送ることが目的なら、末尾のremote_write経路を使います。本稿の設定は公式資料を照合したレビュー版であり、Guanceによる実機テスト済み手順ではありません。

Prometheus remote_readとは何か

Prometheusの用語集は、Remote Readを、クエリの一部として他システムの時系列を透過的に読み取る機能と定義しています。Remote Read adapterは、対象ストレージがこのプロトコルを直接扱えない場合に、Prometheusの要求と対象システムの形式を変換します。

Remote Readは「遠隔のPromQL APIへ式を投げる機能」ではありません。PrometheusのStorage資料によると、Prometheusはlabel selectorと時間範囲に合う生の時系列サンプルをremote endpointから取得し、PromQLの評価自体はクエリを受けたPrometheusで行います。そのため、remote側に/api/v1/queryがあるだけではRemote Read互換とは言えません。

主な利用場面は次のとおりです。

• ローカル保持期間より古いデータを長期保存システムから参照する。
• 移行期間中に、新しいPrometheusから以前のPrometheusの時系列を参照する。
• Remote Read adapterを介して、互換プロトコルを直接実装しないストレージから読む。

一方、Remote Readはデータ移行、バックフィル、複製、Guanceへの送信を自動実行しません。クエリ時に読み取っただけのサンプルを、ローカルTSDBへ永続コピーしたと解釈しないでください。

remote_readとremote_writeの担当範囲

TrueWatchのPrometheus Remote Write資料とGuance版の同資料が説明するDataKitのendpointは、Prometheusからデータを受け取るreceiverです。名前が似ていても、remote_read.urlへ流用できません。

関連ガイドDDTraceをGuanceへ送信する方法：切り替え・検証・ロールバック→

判断を一文にすると、次のようになります。

• Prometheusで第三者ストレージの時系列を検索したい：その製品が示すRemote Read互換endpointをremote_readへ設定する。
• PrometheusのメトリクスをGuanceへ送りたい：DataKitのPrometheus Remote Write collectorを有効にし、remote_writeを設定する。
• PrometheusからGuance保存データをRemote Readで読みたい：公開資料だけでは実装可否もURLも未確認。契約環境の製品資料とGuance担当者による確認が必要。

構成：読み取り経路とGuanceへの書き込み経路

クエリ利用者はquery Prometheusの通常のPromQL APIへアクセスします。query Prometheusは、必要なlabel selectorと時間範囲をRemote Read要求へ変換し、互換endpointからraw samplesを取得します。集約、rate、joinなどのPromQL評価はquery Prometheus側で行われます。

Guanceへの経路は別です。Prometheusが収集したサンプルをremote_writeでDataKitへ送り、DataKitがGuance / TrueWatchへ報告します。両方を同じPrometheusへ設定することは構成上可能ですが、「Remote Readで返った結果が自動的にGuanceへ複製される」とは仮定しません。collection、query、recording rule、remote writeの各経路を別々に検証してください。

証拠・バージョン・テスト状態

Prometheus Remote Read APIは、このAPIがstableではなく、非major release間でも変わり得ると明記しています。したがって、「Prometheus互換」という製品説明だけで判断せず、clientとserverの正確なversion、対応response type、認証方式、最大時間範囲を検証記録へ残します。

本稿の例は現在の公式configuration schemaに合わせていますが、特定のバイナリ組み合わせを保証するものではありません。公開前には、日本語ネイティブ編集、Prometheus運用担当、Guance metrics担当による確認に加え、指定versionでの非本番テストが必要です。

開始前に確認するRemote Read endpointの条件

設定前に、remote storageまたはadapterの公式資料から次を確認します。値を推測で埋めないでください。

1. Remote Read互換URLが明記されている。Prometheus自身をserverにする場合、標準pathは/api/v1/readです。
2. Snappy圧縮とPrometheusのProtocol Buffers request / responseを扱える。
3. SAMPLESまたはSTREAMED_XOR_CHUNKSなど、clientが要求するresponse typeとの互換性がある。
4. 認証、TLS、tenant識別header、証明書のserver nameが文書化されている。
5. 保持期間、最大query range、seriesまたはsample limit、timeout、rate limitが分かる。
6. native histogram、stale marker、external labelなど、利用中のデータ型とlabel contractを確認できる。

GET https://example/api/v1/readをbrowserや通常のcurlで開いてエラーになった、またはHTTP 200になった、という結果だけでは互換性を判定できません。Remote Read requestはbinaryのProtocol BuffersをSnappy圧縮してPOSTするためです。逆に、JSONを返すPromQL query endpointやDataKit DQL endpointが存在しても、Remote Read対応の証拠にはなりません。

最初の検証では、既に時系列を持つsource Prometheusと、ローカルscrapeを行わないquery Prometheusを別に用意すると経路を分離しやすくなります。本番Prometheusへいきなり追加せず、既知の1 metric、1 job、5分程度の時間範囲で始めます。

最小構成：別のPrometheusから読み取る

次は隔離したquery Prometheus用の例です。prometheus-archive.monitoring.svcは説明用の例であり、利用者が自分の内部DNS名へ置き換える前提です。source Prometheusは事前にup{job="prometheus"}を保持し、query Prometheusは同じmetricをローカル収集しないものとします。

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 Read設定をlogやmetricsで区別するために付けます。remote_timeoutの公式defaultは1mですが、ここでは検証時に長時間停止し続けないよう30sを明示しています。短くすれば成功するわけではなく、実際のseries数、network latency、remote側のlimitを測って決めます。

read_recent: trueは、この隔離検証で現在に近いsource dataもremoteへ問い合わせるための設定です。本番でローカルとremoteの保持範囲を分担する場合、defaultのfalseが適切なことがあります。意味を理解せず本番へコピーしないでください。

filter_external_labels: falseは、query Prometheusのexternal_labelsがsource dataのselectorへ意図せず追加される影響を除くための初期検証値です。tenantやclusterをexternal labelで正しく区切る設計なら、label contractを確認したうえでtrueを評価します。

TLSと認証をファイル参照で設定する

remote endpointをネットワーク越しに使う場合は、平文HTTPや設定ファイルへのToken直書きを前提にしません。Prometheusのconfiguration資料で、remote_readは共通HTTP client設定を利用できると説明されています。次はBearer credentialとCAをファイルから読む例です。実際の秘密値は記事、ticket、CI logへ出力しません。

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"

credential fileとprivate keyはPrometheus実行userだけが読める権限にし、backup、support bundle、configuration exportへ混入しないことを確認します。insecure_skip_verify: trueを常用して証明書検証を回避しません。custom headersへsecretを直接書くより、利用可能なら公式のauthorization、basic_auth、oauth2、mTLS設定とsecret fileを使います。

PrometheusのSecurity Modelは、HTTP endpointを不用意にinternetへ公開しないことと、高コストなqueryでserverを過負荷にできる点を説明しています。required_matchersはclient側のrouting guardであり、server側の認証・認可の代わりではありません。network policy、firewall、reverse proxy、TLS、認証、query権限を別に設計します。

設定を検証し、安全にreloadする

まず、稼働中のPrometheusと同じversionのpromtoolで設定を検証します。

promtool check config /etc/prometheus/prometheus.yml

成功しても確認できるのは主に設定の妥当性です。remote endpointのDNS、TLS、credential、response type、データ存在、性能までは証明しません。失敗した場合はreloadせず、表示されたfieldとindentationを修正します。

設定反映は既存の運用手順を優先します。Prometheus Management APIでは、--web.enable-lifecycleが有効な場合にPOSTまたはPUT /-/reloadを使えると説明しています。localhostに限定した例は次のとおりです。

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

/-/reloadがdisabledなら、有効化のために公開範囲を広げるのではなく、SIGHUP、Operator、systemd、rolling updateなど現在承認されている方法を使います。readyが200でもRemote Readのdata pathは未検証です。次のPromQL確認まで行います。

PromQLでRemote Readを実際に確認する

/api/v1/readへ手作りのJSONを送るのではなく、query Prometheusの通常のPromQL APIから既知のmetricを検索します。次の時刻は例なので、source Prometheusが実際にup{job="prometheus"}を保持する5分間へ変更してください。

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'

Prometheus HTTP APIでは、range queryの正常応答はstatus: "success"、resultType: "matrix"とseriesごとのvaluesを返します。最低限の期待形は次です。labelと値は自分のsource dataに合わせて照合します。

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

合格はstatus=successだけではありません。result: []でもquery自体はsuccessになります。次をすべて確認します。

• query Prometheusには対象seriesのローカルscrapeがなく、remote dataを見ていると説明できる。
• source Prometheusへ同じPromQLと時間範囲を直接実行した結果と、metric name、主要label、timestamp、値が一致する。
• query Prometheusの結果に1 series以上、期待したsampleがある。
• remote endpointを一時的に検証用の不正URLへ変える、またはnetworkを遮断した対照試験で、同じqueryが失敗または空になる。
• secret、tenant ID、内部URLを結果やlogの共有資料から除外している。

対照試験は非本番で行い、本番経路を故意に切断しません。query Prometheusが同じseriesをローカルにも保持している場合、Remote Readの成否をquery結果だけで判定できないため、別instance labelまたは過去時間範囲を使います。

sampleがない・一部欠ける場合の排障

時刻の扱いも見落としやすい点です。Remote Read requestはmillisecond timestampを扱い、PromQL APIはRFC3339またはUnix timestampを受け付けます。画面のlocal timezoneとAPIへ渡したUTC範囲を混同しないでください。また、Remote Readは存在しないsampleを補間したり、失敗したscrapeを成功へ変えたりしません。

network確認ではDNS、TLS handshake、proxy、service mesh、NetworkPolicyを分けて調べます。ただし、単純なTCP接続成功はProtocol Buffers互換の証拠ではありません。最終判定はPrometheusからの実queryと期待sampleの比較で行います。

read_recent・external_labels・required_matchersの落とし穴

read_recent

公式schemaではdefaultがfalseです。これは、ローカルstorageが完全なdataを持つはずの時間範囲までremoteへ読みに行くかを制御します。最近のdataしかない検証環境でfalseのままにすると、remoteへ接続できていても空に見えることがあります。一方、重複範囲を常にremoteへ問い合わせる設計はlatencyと負荷を増やし、local dataとの境界を分かりにくくします。

filter_external_labels

defaultはtrueです。query Prometheusのexternal_labelsをremote selectorへ使うため、remote側のlabel contractと異なる値があると期待seriesを絞り落とす可能性があります。単一clusterの隔離テストではfalseにして影響を外し、本番設計ではtenant、cluster、regionの一致を確認して明示的に決めます。

required_matchers

指定したequality matcherがquery selectorに含まれる場合だけ、そのRemote Read endpointを使うためのguardです。例えばremote側の全seriesが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"}はこのremoteへroutingされません。高カーディナリティなrequest IDやuser IDを必須matcherに使わず、安定した低カーディナリティlabelを使います。繰り返しますが、これは認可ではありません。

timeoutとlabel cardinalityを制御する

Remote Readでは、remote側からraw seriesを取得してPromQLをquery Prometheusで評価します。そのため、{__name__=~".+"}のような広いselector、長い時間範囲、高カーディナリティlabelの組み合わせは、remote、network、query PrometheusのCPUとmemoryへ同時に影響します。streaming responseを使っても、無制限なqueryが安全になるわけではありません。

関連ガイドAPMとは？仕組み・監視項目・オブザーバビリティとの違いを実務で解説→

最初の性能検証は次の順で広げます。

1. 既知のmetricを1つ指定する。
2. job、cluster、serviceなどの低カーディナリティmatcherでseriesを限定する。
3. 5分、1時間、6時間と時間範囲を段階的に広げる。
4. series数、sample数、response size、remote latency、query PrometheusのCPU・memoryを記録する。
5. dashboard、alert、recording ruleの実queryを1本ずつ再現する。
6. timeout時に利用者へ返るerrorと、retryによる負荷増幅を確認する。

remote_timeoutだけを長くして解決したことにしないでください。原因が広すぎるselectorなら、待ち時間とresource消費を延ばすだけです。query APIのtimeout、Prometheus server全体のquery timeout、reverse proxy、remote storage側のtimeoutは別々の制限です。最短の制限が先に発火します。

TrueWatch Metrics資料も、time series数がstorage costとquery performanceへ直接影響すると説明しています。Remote Readの性能と、GuanceへRemote Writeした後の保存設計は別ですが、どちらもdynamicなuser_id、request ID、完全URLなどを無制限labelへしないという基本設計は共通です。

protocol互換性をどう判定するか

Remote ReadはHTTP上でSnappy圧縮したProtocol Buffersを使い、標準pathはPrometheus serverの/api/v1/readです。公式APIはraw samplesとstreamed chunksを説明しています。Prometheusのstreaming設計資料で説明されるstreamed modeは大きな応答をframeへ分けますが、clientとserverの対応が必要です。

互換性確認では次を記録します。

• query Prometheusの正確なversionとbuild情報。
• remote storageまたはadapterの正確なversion。
• endpoint path、TLS、認証、tenant routing。
• SAMPLESとSTREAMED_XOR_CHUNKSの対応状況。
• float samples、native histograms、stale markersの扱い。
• 最大frame、series、sample、時間範囲、並行queryの制限。
• 失敗時のHTTP status、Prometheus log、remote側log。

Prometheus公式はRemote Read APIをstableと見なしていないため、「Prometheus 3対応」「PromQL対応」といった広い表現だけでは合格にしません。minor upgradeでも同じ検証queryを再実行し、少なくとも1つのfloat metric、利用中ならhistogram、欠損区間、timeoutを確認します。

Guanceへ送る場合はremote_writeを使う

目的が「Prometheusで収集したメトリクスをGuance / TrueWatchで保存・分析する」ことであれば、Remote Read endpointを探す必要はありません。DataKitでPrometheus Remote Write collectorを有効にし、Prometheus側へ次の方向を設定します。

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

DataKit側ではprom_remote_write.conf.sampleをprom_remote_write.confとして管理し、path = "/prom_remote_write"を確認します。実環境ではDataKit listenerをinternetへ直接公開せず、network control、TLS終端、認証、metric filter、tag設計を確認してください。公開資料にはBasic Authの設定例もありますが、credentialを本稿へ載せません。

Guance / TrueWatch内では、Metrics AnalysisでPromQL query modeを利用できます。これは製品内に保存されたmetricsをPromQLで分析する機能であり、外部Prometheusへ/api/v1/readを提供することと同義ではありません。

また、DataKitのRemote Write collectorはmetric nameのmapping設定を持ちます。既存PromQL、dashboard、alertとの互換性を評価する場合は、job_as_measurement、measurement_name、keep_exist_metric_name、tag filter / renameを固定し、送信前後の名前を実dataで比較します。「受信HTTPが2xxだった」だけでquery互換まで合格にしません。

ロールバック手順

Remote Read設定は、他の同時変更と分離した差分として管理します。rollbackは次の順で行います。

1. 変更前のprometheus.yml、Prometheus version、remote endpoint、認証file参照、external labelsを保存していることを確認する。
2. 対象のremote_read entryだけを削除するか、承認済みの以前の値へ戻す。
3. promtool check config /etc/prometheus/prometheus.ymlを実行する。
4. 通常の運用手順でreloadまたはrolling updateする。
5. /-/readyとローカルmetricsの既知queryを確認する。
6. remoteにしか存在しない対照queryが結果を返さなくなり、ローカルqueryとalertが正常であることを確認する。
7. 一時credential、検証用network rule、debug logを承認済みの方法で整理する。

Remote Readはquery pathなので、設定を外してもremote storageの原データを削除しません。逆に、remote側のデータをローカルへ永続移行したことにもなりません。Guance向けremote_writeを同時に使っている場合、Remote Readのrollbackに巻き込んで削除せず、別のownerと合格条件で扱います。

本番化前の合格条件

最低でも代表的なdashboard、alert、ad-hoc queryを含む評価期間を設け、次を説明できる状態にします。

• 正確なPrometheus / storage / adapter versionとcompatibility根拠がある。
• 既知のhistorical rangeでsourceとquery Prometheusのseries、label、timestamp、valueが一致する。
• read_recent、filter_external_labels、required_matchersの採用理由が記録されている。
• empty result、partial samples、timeout、remote unavailableを再現し、利用者への影響が分かる。
• 広いrangeと本番相当cardinalityでCPU、memory、network、latencyが許容範囲にある。
• credential rotation、TLS更新、tenant分離、network restrictionを確認した。
• rollback演習でremote entryだけを戻し、ローカルqueryとalertを復旧できた。
• GuanceへのRemote Writeを併用する場合、metric naming、tag、data volume、query結果を別途検証した。

「1回seriesが見えた」「HTTP 200だった」「PromQLが書けた」のいずれか一つだけでは本番合格にしません。Remote Readがquery availabilityへ新しい依存先を追加するため、remote outage時のdashboardとalertの挙動も必要です。

公開資料に記載されていませんと公開できない主張

2026年8月1日時点で、次を公開資料に記載されていませんとして残します。

• Guance / TrueWatch SaaSがPrometheus Remote Read互換endpointを契約者へ提供するか、そのURL、region、認証、limit、SLA。
• 読者環境のPrometheusとremote storage / adapterの正確な互換性。
• native histogram、streamed chunks、stale markerの実dataでの挙動。
• 読者環境のseries cardinality、保持期間、query timeout、network latency。
• Remote Readと既存recording rules、alerts、dashboardの完全な等価性。
• 日本向けSaaS endpointとdata residencyの関係。endpointの地域名だけでは保管場所を証明できない。

したがって、「GuanceからPrometheusへそのままRemote Readできる」「完全互換」「無制限query」「欠損ゼロ」「移行不要」「全version対応」「zero downtime」とは表現しません。GuanceのRemote Read提供有無が製品担当により確認できた場合も、公式URL、protocol、region、認証、version、limitを文書化してから本稿を更新します。

公式資料

本稿は次の一次資料を2026年8月1日に確認し、文書で確認できた事実と運用上の推論を分けて記載しました。

1. Prometheus — Storage / Remote storage integrations — read / writeの方向、wire format、PromQLのlocal evaluation、scalability上の注意。
2. Prometheus — Configuration / remote_read — url、name、required_matchers、remote_timeout、read_recent、filter_external_labels、HTTP client設定。
3. Prometheus — Remote Read API — /api/v1/read、Snappy、Protocol Buffers、samples、streamed chunks、unstable status。
4. Prometheus — Glossary — Remote Read、Remote Read adapter、Remote Writeの定義。
5. Prometheus — HTTP API — instant / range query、timeout、JSON response。
6. Prometheus — Management API — health、ready、reloadとlifecycle flag。
7. Prometheus — Security Model — HTTP endpoint、query load、TLS、authentication、secretの注意。
8. Prometheus — promtool command reference — promtool check config。
9. Prometheus — Remote Read Meets Streaming — SAMPLES、STREAMED_XOR_CHUNKSと互換性の設計背景。
10. TrueWatch Docs — Prometheus Remote Write — DataKit receiver、/prom_remote_write、metric naming、filter、tag設定。
11. Guance Docs — Prometheus Remote Write — Guance側の同collector設定。
12. TrueWatch Docs — Metrics — metrics data path、time seriesとquery performance、製品内PromQL。
13. TrueWatch Docs — Metrics Analysis — Guance / TrueWatch内のPromQL query mode。
14. Guance Docs — DataKit HTTP API — DataKitのwrite / query API。Remote Readの代替ではないことを確認するために参照。