Prometheus remote_read 설정: 쿼리 검증과 운영 한계

Prometheus remote_read는 다른 Prometheus나 호환 스토리지에서 시계열을 읽어 일반 PromQL 쿼리에 포함하는 기능입니다. 데이터를 조회하는 경로이며, 수집한 샘플을 외부 수신기로 보내는 remote_write와는 방향과 역할이 다릅니다.

먼저 Guance와의 연결 범위를 구분해야 합니다. 2026년 10월 27일에 확인한 Guance·TrueWatch 공개 문서에는 DataKit의 /prom_remote_write 수신기와 제품 내부 DQL·PromQL 조회가 설명되어 있습니다. 그러나 외부 Prometheus가 사용할 Guance 관리형 Remote Read URL, 인증 및 호환 조건은 확인되지 않았습니다. 이는 공개 자료의 한계이며, 모든 배포에서 해당 기능을 제공하지 않는다는 뜻은 아닙니다. /prom_remote_write나 DataKit의 /v1/query/raw를 remote_read.url에 넣으면 안 됩니다.

이 글은 다른 Prometheus 또는 Remote Read 지원이 명시된 스토리지에서 데이터를 읽는 방법을 다룹니다. 지표를 Guance로 보내려면 뒤의 Remote Write 절을 참고하세요. 설정은 공식 문서와 대조했지만, 이번 검토에서 특정 버전 조합의 전송·인증·롤백을 실제로 실행하지는 않았습니다.

Remote Read가 가져오는 데이터

Prometheus는 라벨 조건과 시간 범위에 맞는 원시 시계열을 요청한 뒤, 조회를 받은 서버에서 PromQL을 계산합니다. 임의의 PromQL 식을 원격 시스템에 보내 분산 실행하는 방식이 아닙니다. 따라서 /api/v1/query가 있다는 사실만으로 Remote Read 호환성을 판단할 수 없습니다.

로컬 보존 기간보다 오래된 데이터를 조회하거나, 마이그레이션 중 기존 Prometheus를 참조하거나, 어댑터로 다른 스토리지를 연결할 때 사용할 수 있습니다. 다만 쿼리 결과가 반환되었다고 로컬 TSDB에 백필되거나, 전체 데이터가 복제되거나, Guance로 자동 전송된 것은 아닙니다.

다른 스토리지를 읽으려면 그 제품이 지원하는 Remote Read 주소를 사용합니다. Prometheus 지표를 Guance에 저장·분석하려면 DataKit Remote Write를 설정합니다. Guance에 저장된 지표를 Prometheus로 읽어오려면 먼저 해당 배포의 제품 문서에서 인터페이스를 확인해야 합니다.

읽기와 쓰기 경로를 따로 검증하기

사용자는 조회 Prometheus의 일반 PromQL API에 요청합니다. 해당 서버가 필요한 원시 시계열을 가져와 집계, rate, 조인 등을 계산합니다. Guance로 보내는 경로에서는 로컬에 수집된 샘플을 remote_write로 DataKit에 전달하고 워크스페이스에 업로드합니다.

한 Prometheus에 두 설정을 함께 둘 수는 있습니다. 하지만 Remote Read 조회 결과가 Remote Write로 자동 복제된다고 가정해서는 안 됩니다. 수집, 조회, recording rule, 외부 전송을 각각 검증하세요.

이번 문서 검토에서 확인한 범위

2026년 10월 27일 검토에서는 remote_read 스키마와 기본값, /api/v1/read 프로토콜, DataKit의 쓰기·DQL API, 제품 내 PromQL 모드를 확인했습니다. Guance 관리형 Remote Read의 공개 인터페이스나 독자의 실제 바이너리 조합을 검증한 것은 아닙니다.

Prometheus는 Remote Read를 안정 API로 분류하지 않습니다. 메이저 버전이 아닌 업데이트에서도 변경될 수 있습니다. 조회 서버와 스토리지·어댑터의 정확한 버전, 응답 형식, 인증, 제한을 기록해야 합니다. “Prometheus 호환”이라는 설명만으로 특정 경로가 작동한다고 결론 내릴 수는 없습니다.

운영 적용 전에는 실제 요청, 인증, 쿼리 결과, 타임아웃, 롤백을 사용하는 버전으로 시험하세요. 문서 검토는 이 환경 검증을 대신하지 않습니다.

endpoint 조건부터 확인하기

원격 제품 또는 어댑터의 공식 문서에서 다음을 확인합니다.

• 명시된 Remote Read URL. Prometheus 자체의 경로는 /api/v1/read입니다.
• Snappy로 압축한 Protocol Buffers 요청과 호환 응답.
• SAMPLES, STREAMED_XOR_CHUNKS 등 필요한 응답 형식.
• TLS, 인증, 테넌트 헤더, 인증서 server name.
• 보존 기간, 최대 조회 범위, series/sample 수, 타임아웃, 요청 제한.
• Native histogram, stale marker, external label 처리.

브라우저에서 GET으로 열었을 때 오류 또는 HTTP 200이 나와도 호환성 증거가 되지 않습니다. Remote Read는 이진 Protocol Buffers를 POST로 보내며, 직접 작성한 JSON PromQL 요청과 다릅니다.

첫 시험은 알려진 지표가 있는 source Prometheus와, 같은 시계열을 로컬에서 수집하지 않는 별도 query Prometheus로 나누면 경로를 구분하기 쉽습니다. 지표 하나, job 하나, 약 5분 범위부터 시작합니다.

최소 설정 예제

아래 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 클라이언트 설정을 사용합니다. 네트워크를 넘는 연결에서는 인증과 인증서 검증을 구성하고, 비밀을 본문에 직접 쓰거나 검증을 끄는 방식에 의존하지 않습니다.

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, 서비스 관리자 또는 롤링 업데이트 절차를 사용합니다. reload를 편하게 하려고 공개 접근 범위를 넓히지 않습니다. ready 응답은 요청을 처리할 준비가 되었다는 뜻일 뿐, Remote Read 결과를 검증하지 않습니다.

일반 PromQL API에서 실제 결과 확인하기

/api/v1/read에 임의 JSON을 보내지 말고 query 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'

성공한 range query는 matrix를 반환합니다. 다음은 축약한 응답 형식 예제이며, 이번 검토의 실제 시험 결과가 아닙니다.

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

빈 result도 status: "success"로 반환될 수 있습니다. 다음까지 확인해야 합니다.

1. 조회 서버의 로컬 scrape 경로에 해당 시계열이 없어 결과가 원격에 의존합니다.
2. 소스에 같은 식과 시간 범위를 직접 조회해 이름, 예상 라벨, 타임스탬프, 값을 비교합니다. External label 변환을 고려합니다.
3. 예상 시계열과 샘플이 하나 이상 있습니다.
4. 격리 시험에서만 원격 URL을 의도적으로 잘못 지정하거나 해당 연결을 차단합니다. 원격에만 존재하는 데이터의 조회가 실패하거나 비어야 합니다.
5. 공유할 증거에서 테넌트 식별자, 비밀, 내부 URL을 제거합니다.

로컬에도 같은 시계열이 있다면 성공한 쿼리가 원격 장애를 가릴 수 있습니다. 별도 instance나 과거 구간으로 분리하세요. 대조 시험을 위해 운영 경로를 끊으면 안 됩니다.

빈 결과와 누락, 타임아웃 좁혀 보기

Remote Read 프로토콜의 타임스탬프는 밀리초 단위입니다. PromQL HTTP API는 RFC3339 또는 Unix 타임스탬프를 받습니다. 화면의 현지 시간과 요청의 UTC 구간을 혼동하지 마세요. Remote Read가 없는 샘플을 채우거나 실패한 scrape를 성공으로 바꾸지는 않습니다.

네트워크 확인은 DNS, TLS handshake, 프록시, Service Mesh, NetworkPolicy를 분리합니다. TCP 연결 성공은 프로토콜 호환성 증거가 아니며, 최종 판단은 실제 Prometheus 쿼리와 예상 샘플 비교로 합니다.

세 가지 설정의 의미

read_recent의 기본값은 false입니다. 로컬 스토리지가 완전한 데이터를 보유한다고 기대하는 구간도 원격에 조회할지를 정합니다. 중복 구간을 항상 원격에 요청하면 지연과 부하가 늘 수 있으므로 의도적으로 선택해야 합니다.

filter_external_labels의 기본값은 true입니다. 조회 서버는 자신의 external label을 추가 완전 일치 matcher로 보내고, 응답에서 자신이 추가한 라벨을 제거할 수 있습니다. 데이터를 제공하는 Prometheus도 /api/v1/read 응답 시 자신의 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"}는 해당 endpoint를 선택할 수 있지만, http_requests_total{job="api"}는 그렇지 않습니다. 사용자·요청 ID 대신 안정적인 낮은 카디널리티 라벨을 사용합니다. 이 조건은 접근 권한을 제공하지 않습니다.

타임아웃을 늘리기 전에 쿼리 크기 줄이기

조회 서버가 원시 데이터를 받아 직접 처리하므로, {__name__=~".+"} 같은 넓은 selector와 긴 시간 범위, 높은 카디널리티가 겹치면 스토리지·네트워크·CPU·메모리가 함께 영향을 받습니다. 스트리밍 응답도 무제한 쿼리를 안전하게 만들지는 않습니다.

지표 하나와 job, cluster, service 조건부터 시작합니다. 5분, 1시간, 6시간 순서로 범위를 늘리며 시계열·샘플 수, 응답 크기, 원격 지연, 조회 서버 자원을 기록합니다. 실제 대시보드, 알림, recording rule 식을 하나씩 재현하고, 타임아웃 오류와 재시도가 부하를 키우는지 확인합니다.

remote_timeout, API의 timeout, 서버 query timeout, 역방향 프록시 및 스토리지 제한은 별개입니다. 적용되는 제한 중 가장 짧은 것이 먼저 끝납니다. 한 항목을 늘린다고 넓은 selector 문제가 해결되지는 않습니다.

Guance에 지표를 저장할 때도 무제한 user_id, 요청 ID, 전체 URL 라벨은 피해야 합니다. 다만 저장 설계와 Remote Read 성능 검증은 별도 작업입니다.

호환성은 버전 단위로 판단하기

Remote Read는 HTTP에서 Snappy로 압축한 Protocol Buffers 요청을 사용합니다. Prometheus endpoint는 /api/v1/read이며 샘플 응답과 스트리밍 chunk 응답이 문서화되어 있습니다. 스트리밍은 큰 응답을 frame으로 나누지만 양쪽에서 협상한 형식을 지원해야 합니다.

클라이언트와 스토리지·어댑터의 정확한 build, URL, TLS, 인증, 테넌트 경로를 기록합니다. SAMPLES, STREAMED_XOR_CHUNKS, 부동소수점 샘플, native histogram, stale marker와 frame·series·sample·시간 범위·동시성 제한도 확인합니다. 오류 발생 시 HTTP 상태와 양쪽 로그를 비밀 없이 보관합니다.

업그레이드 후에는 부동소수점 지표 하나, 사용하는 histogram, 누락 구간, 타임아웃을 다시 시험합니다. “Prometheus 3 지원”이나 “PromQL 지원”은 이 수준의 검증을 대체하지 않습니다.

Guance로 보내려면 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 예제를 사용할 때도 실제 비밀번호를 글이나 티켓에 넣지 않습니다.

Metrics Analysis의 PromQL은 제품에 저장된 지표를 조회합니다. 외부 Prometheus에 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. 기존 절차로 reload 또는 rollout합니다.
5. /-/ready, 알려진 로컬 쿼리와 알림을 확인합니다.
6. 원격에만 있는 대조 쿼리가 이 항목을 통해 더 이상 데이터를 반환하지 않는지 확인합니다.
7. 시험용 인증 정보, 네트워크 예외, 디버그 로그를 정상 절차로 정리합니다.

Remote Read 제거는 원격 원본 데이터를 삭제하지 않습니다. 앞선 조회가 데이터를 로컬에 영구 이전한 것도 아닙니다. Guance Remote Write를 함께 사용하더라도 별도 변경 계획이 요구하지 않는 한 함께 제거하지 않습니다.

운영 적용을 판단할 증거

대표 대시보드·알림·임시 쿼리를 포함하는 평가 기간을 둡니다. 정확한 버전 호환 근거, 예상 샘플과 라벨, 세 설정의 선택 이유, 실패·타임아웃 동작, 실제 카디널리티에서의 부하, 인증 정보·TLS 교체, 테넌트 경계, 성공한 롤백 기록이 필요합니다. Remote Write를 병행하면 이름·전송량·쿼리도 별도 검증합니다.

시계열 하나, HTTP 200 또는 유효한 PromQL 식만으로 운영 준비가 끝난 것은 아닙니다. Remote Read는 쿼리 가용성에 새로운 외부 의존성을 추가하며, 그 장애가 대시보드와 알림 계산에도 영향을 줄 수 있습니다.

아직 필요한 증거는 무엇인가

프로토콜 방향, 기본값, 로컬 PromQL 계산은 문서로 확인했습니다. 남은 항목은 성격이 다르므로 모두 “문서 미확인”으로 묶으면 안 됩니다.

• 제품 자료: 검토한 공개 문서는 Guance 관리형 Remote Read URL, 프로토콜, 인증, 테넌트 및 제한을 정의하지 않습니다. 해당 경로를 구현하기 전에 적용 가능한 인터페이스 문서를 확보해야 합니다.
• 환경 시험: 실제 버전 조합, 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: 설정 검사와 reload.
6. 보안 모델과 Remote Read 스트리밍: endpoint 노출, 부하, 프로토콜 설계.
7. TrueWatch Remote Write와 Guance Remote Write: 수신기와 지표 이름 변환.
8. TrueWatch Metrics와 Metrics Analysis: 제품 지표와 PromQL.
9. DataKit HTTP API: 워크스페이스 DQL과 Remote Read의 차이.