콘텐츠 협상

콘텐츠 협상 (Content negotiation)

이 문서는 Prometheus의 HTTP 콘텐츠 협상(content negotiation) 동작을 설명해요. 클라이언트가 Accept 헤더를 보내면, Prometheus가 스크레이프 요청에서 어떤 형식으로 메트릭을 반환할지 결정합니다. 기본적으로 Prometheus는 요청된 형식 중 자신이 지원하는 형식(텍스트/일반, OpenMetrics, protobuf 등)을 선택해 응답합니다.

스크레이프 시 Prometheus는 서버가 노출하는 형식에 맞춰 응답을 해석합니다. 익스포저 쪽에서도 같은 협상 규칙에 따라 적절한 형식을 제공해야 합니다.

출처: 문서

본문

Prometheus는 HTTP 콘텐츠 협상을 지원합니다. 클라이언트(Prometheus 서버)가 Accept 헤더로 선호하는 형식을 알리면, 서버(엑스포터)가 그중 지원하는 형식으로 메트릭을 반환합니다.

지원되는 형식

Prometheus가 인식하는 주요 응답 형식은 다음과 같습니다:

  • text/plain; version=0.0.4; charset=utf-8 — 전통적인 Prometheus 텍스트 형식(레거시).
  • application/openmetrics-text; version=1.0.0; charset=utf-8 — OpenMetrics 텍스트 형식.
  • application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited — protobuf(구형).

Prometheus 클라이언트 라이브러리(예: Go/Python)는 promhttp.Handler() 같은 핸들러에서 요청의 Accept 헤더를 보고 가장 적합한 형식을 자동으로 선택해 응답을 생성합니다.

예를 들어 Go 클라이언트는:

  • Accept: application/openmetrics-text → OpenMetrics 형식 응답.
  • Accept: text/plain → 텍스트 형식 응답.
  • 협상 실패 시 기본 형식으로 응답합니다.

스크레이프 시 동작

Prometheus 서버가 엑스포터를 스크레이프할 때도 동일한 HTTP 협상이 일어납니다. Prometheus는 서버가 반환한 Content-Type을 보고 메트릭을 파싱합니다.

  • 엑스포터가 OpenMetrics 형식을 반환하면 Prometheus는 이를 지원합니다.
  • 형식이 명확하지 않거나 지원되지 않는 형식이면 에러가 날 수 있습니다.

엑스포터 고려 사항

엑스포터를 만들 때는:

  • 요청의 Accept 헤더를 존중해 적절한 형식으로 응답하세요.
  • 가능하면 OpenMetrics 형식(application/openmetrics-text)을 지원하는 것이 좋습니다(최신 기능과 단위 지원).
  • 지원하지 않는 형식이 요청되면 기본 형식(텍스트)으로 폴백하거나 적절한 상태를 반환합니다.

더 알아보기 (Learn more)