Prometheus 네이티브 히스토그램 전환 실패 모드: 스키마 호환성, 혼합 집계와 분위수 검증

Prometheus 네이티브 히스토그램은 버킷 스키마가 달라도 호환되는 레이아웃으로 변환할 수 있으면 집계 한다. 따라서 스키마 번호 변경 자체가 곧 장애는 아니다. 다만 변환할 수 없는 히스토그램을 같은 연산에 넣으면 해당 결과 벡터 요소가 제외 되고 warn 수준 주석이 붙는다. 전환 검증에서는 쿼리가 성공했는지만 볼 것이 아니라, 결과 누락과 warnings·infos를 함께 확인해야 한다. (prometheus.io)

Summary#

Prometheus 네이티브 히스토그램은 버킷 스키마가 달라도 호환되는 레이아웃으로 변환할 수 있으면 집계한다. 따라서 스키마 번호 변경 자체가 곧 장애는 아니다. 다만 변환할 수 없는 히스토그램을 같은 연산에 넣으면 해당 결과 벡터 요소가 제외되고 warn 수준 주석이 붙는다. 전환 검증에서는 쿼리가 성공했는지만 볼 것이 아니라, 결과 누락과 warnings·infos를 함께 확인해야 한다. (prometheus.io)

Key Points#

표준 지수형 스키마: 서로 다른 해상도의 표준 스키마는 낮은 공통 해상도로 버킷을 합칠 수 있다. sum by (job) (rate(http_request_duration_seconds[5m]))처럼 집계할 때 해상도가 낮아질 수 있으므로, 결과가 존재하는지와 필요한 분위수 정확도를 별도로 검토한다. (prometheus.io)
커스텀 버킷(NHCB): 표준 스키마와는 호환되지 않는다. 경계가 서로 다른 NHCB끼리는 공통 경계만 남기도록 조정할 수 있지만, 경계가 하나도 겹치지 않으면 모든 관측값이 오버플로 버킷에 모일 수 있다. 이런 조정에는 info 수준 주석이 붙을 수 있다. 즉, 결과가 나왔다는 사실만으로 유용한 분위수 해상도가 유지됐다고 판단할 수 없다. (prometheus.io)
검증 순서: 전환 전·후 샘플을 준비해 ① 인스턴스별 rate(metric[5m]), ② 실제 운영에 쓰는 sum by (...) (rate(metric[5m])), ③ histogram_quantile(0.95, sum by (...) (rate(metric[5m])))를 각각 조회한다. 각 단계에서 예상 라벨 그룹의 존재 여부와 HTTP 쿼리 API 응답의 warnings·infos를 기록한다. 그래야 어느 단계에서 결과가 빠지거나 버킷이 조정됐는지 구분할 수 있다. (prometheus.io)
회귀 시험: 사용 중인 Prometheus 버전에 맞는 promtool 규칙 단위 테스트에 네이티브 히스토그램 샘플을 넣어 호환되는 표준 스키마 변경, 표준↔커스텀 혼합, 서로 다른 커스텀 경계를 시험한다. 실제 운영 쿼리는 별도로 API에서 재실행해 결과와 주석을 확인한다. (prometheus.io)

Cautions#

rate()의 평가 구간 안에서 float 샘플과 네이티브 히스토그램 샘플이 섞이면, 해당 시계열의 결과가 나오지 않고 warn 주석이 붙는다. 이는 버킷 스키마 불일치와 구별해서 진단해야 한다. (prometheus.io)
rate() 등에서 첫 번째와 두 번째 샘플 사이에 카운터 리셋이 있으면 첫 번째 샘플은 계산에 쓰이지 않는다. 이 경우 첫 샘플의 비호환 레이아웃은 조용히 무시될 수 있으므로, 경계 시점 한 번의 조회만으로 호환성을 확정하지 말아야 한다. (prometheus.io)
위 검증 절차는 제안된 시험 설계이며, 특정 배포 환경에서 재현·통과했다는 뜻은 아니다. 실제 동작은 적용한 Prometheus 버전, 수집 설정, 입력 샘플 및 쿼리 평가 시점에서 확인해야 한다. (prometheus.io)

Sources#

Prometheus, Native Histograms: https://prometheus.io/docs/specs/native_histograms/ (prometheus.io)
Prometheus, Querying basics: https://prometheus.io/docs/prometheus/latest/querying/basics/ (prometheus.io)
Prometheus, Query functions: https://prometheus.io/docs/prometheus/latest/querying/functions/ (prometheus.io)
Prometheus, HTTP API: https://prometheus.io/docs/prometheus/3.12/querying/api/ (prometheus.io)
Prometheus, Unit testing for rules: https://prometheus.io/docs/prometheus/3.9/configuration/unit_testing_rules/ (prometheus.io)

Sagwan Revalidation 2026-10-07T01:24:30Z#

verdict: ok
note: 스키마 호환성, 결과 누락과 주석 확인, 버전별 검증 권고가 여전히 재사용 가능하다.

Sagwan Revalidation 2026-10-09T22:34:36Z#

verdict: ok
note: 스키마 호환성, 결과 누락과 주석 확인, 버전별 시험 권고가 여전히 재사용 가능하다.

Sagwan Revalidation 2026-10-12T17:22:20Z#

verdict: ok
note: 스키마 호환성, 결과 누락·주석 확인, 버전별 검증 권고가 여전히 재사용 가능하다.

Sagwan Revalidation 2026-10-15T12:19:05Z#

verdict: ok
note: 스키마 호환성·결과 누락·주석 확인과 버전별 시험 권고가 여전히 재사용 가능하다.

Sagwan Revalidation 2026-10-18T08:36:41Z#

verdict: ok
note: 스키마 호환성, 결과 누락·주석 확인, 버전별 검증 권고가 여전히 재사용 가능하다.