익스포지션 형식

익스포지션 형식 (Exposition formats)

이 문서는 Prometheus가 메트릭을 노출(익스포지션)할 때 사용하는 형식들을 설명해요. 핵심은 **텍스트 형식(text format)**으로, 클라이언트 라이브러리와 엑스포터가 /metrics 엔드포인트에서 이 형식으로 메트릭을 내보냅니다. 그 외에 protobuf 형식도 있습니다.

메트릭을 직접 노출하는 코드를 짜거나, 익스포저를 만들 때 이 형식 규칙을 이해하면 올바른 응답을 만들 수 있어요. 카운터·게이지·히스토그램·요약이 각각 어떤 행으로 표현되는지가 핵심입니다.

출처: 문서

본문

텍스트 형식 (Text format)

Prometheus의 메트릭 익스포지션은 텍스트 형식이 기본입니다. 텍스트 응답은 일련의 라인으로 구성됩니다. 빈 줄과 주석(#)은 무시됩니다. 각 라인은 주석, HELP/TYPE 정보, 또는 메트릭 표본입니다.

메타데이터 라인

# HELP는 메트릭의 설명을, # TYPE은 메트릭 타입을 나타냅니다:

# HELP http_requests_total The total number of HTTP requests.
# TYPE http_requests_total counter

TYPE에는 counter, gauge, histogram, summary, untyped가 있습니다.

메트릭 표본

메트릭 표본은 메트릭 이름(컬렉터 이름), 라벨, 값(선택적 타임스탬프)으로 구성됩니다.

게이지/카운터 예시:

http_requests_total{method="post",code="200"} 1027 1395066363000
http_requests_total{method="post",code="400"} 3 1395066363000

라벨은 {name="value",...} 형식이며, 값은 부동소수점(NaN, +Inf, -Inf 가능)입니다. 타임스탬프는 선택적이며 밀리초 단위입니다.

히스토그램과 요약

히스토그램은 _bucket 라벨로 버킷 경계를 나타내고, _sum과 _count 접미사가 붙은 추가 표본이 있습니다:

# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.05"} 24054
http_request_duration_seconds_bucket{le="0.1"} 33444
http_request_duration_seconds_bucket{le="+Inf"} 144320
http_request_duration_seconds_sum 53423
http_request_duration_seconds_count 144320

요약(summary)은 quantile 라벨로 분위수를 나타내며 _sum과 _count가 함께 있습니다.

주석

#으로 시작하는 주석은 무시됩니다. 다만 # HELP와 # TYPE은 특별하게 처리됩니다.

프로토버프 형식

Prometheus는 구형으로 protobuf 기반 형식도 지원합니다. 이는 io.prometheus.client.MetricFamily 메시지를 delimited protobuf로 인코딩한 것입니다. 새 구현에서는 텍스트 형식(또는 OpenMetrics)을 권장합니다.

형식 버전과 콘텐츠 협상

클라이언트는 Accept 헤더로 선호 형식을 알리고, 서버는 지원하는 형식으로 응답합니다(콘텐츠 협상 참조).

더 알아보기 (Learn more)