6.9 KiB
title, source_type, url, archive_url, related_branches, related_projects, tags, created
| title | source_type | url | archive_url | related_branches | related_projects | tags | created | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Prometheus — Histograms and Summaries Practices | official-doc | https://prometheus.io/docs/practices/histograms/ |
|
|
|
2026-06-14 |
Prometheus — Histograms and Summaries Practices
Layer:
raw/— 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은/ingest후wiki/concepts/에 별도 작성. 원본은 raw에 영구 보관.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-metrics-alerting-contract | D9 — client-side percentiles(Summary 유사)를 인스턴스 간 평균내면 통계적으로 무의미하다는 Prometheus 공식 경고. histogram + histogram_quantile() 로 집계해야 한다는 근거. |
출처 / Source
- 원본 URL: https://prometheus.io/docs/practices/histograms/
- 아카이브 URL:
- 저자 / 조직: Prometheus Authors (prometheus.io)
- 발행일: (날짜 미명시 — 공식 문서 지속 갱신)
- 마지막 확인일: 2026-06-14
왜 저장했는지 / Why archived
Prometheus 공식 문서가 Summary의 pre-computed quantile은 인스턴스 간 집계(averaging)가 통계적으로 무의미함을 명시적으로 경고하고, histogram + histogram_quantile() 함수를 사용한 집계를 공식 권장 방법으로 제시한다. branch feature-metrics-alerting-contract 의 D9 결정(publishPercentiles 대신 histogram 기반 집계 사용)의 직접 근거다.
핵심 인용 / Key quotes (verbatim)
[§Quantiles — "averaging" 경고] "In this particular case, averaging the quantiles yields statistically nonsensical values."
[§Quantiles — BAD example]
`avg(http_request_duration_seconds{quantile="0.95"}) // BAD!
[§Quantiles — GOOD example, classic histogram]
`histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m]))) // GOOD.
[§Rules of thumb — selection guidance] "Only if aggregation isn't needed, you can start thinking about summaries."
[§Introduction — top-level recommendation] "The most important lesson to learn from this document is simple: If you can, use native histograms and prefer them over both classic histograms and summaries."
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| PROM-HIST-C1 | Summary의 pre-computed quantile을 여러 인스턴스에 걸쳐 평균내는 것은 통계적으로 무의미한 값을 만든다 | [§Quantiles] "In this particular case, averaging the quantiles yields statistically nonsensical values." | official-vendor-doc |
Prometheus Summary metric type 을 사용하는 모든 분산 시스템 | client-side가 아닌 single-instance 단일 서버에서 Summary를 읽는 경우에는 해당 없음 |
| PROM-HIST-C2 | avg(metric{quantile="0.95"}) 패턴은 BAD — 잘못된 aggregation |
[§Quantiles] `avg(http_request_duration_seconds{quantile="0.95"}) // BAD! |
official-vendor-doc |
PromQL 쿼리 작성 시 quantile label이 있는 Summary metric에 avg() 적용하는 패턴 | Gauge나 Counter type에 avg를 쓰는 경우는 별개 |
| PROM-HIST-C3 | Classic histogram을 여러 인스턴스에 걸쳐 올바르게 집계하는 방법은 histogram_quantile(φ, sum by (le) (rate(bucket[window]))) |
[§Quantiles] `histogram_quantile(0.95, sum by (le) (rate(http_request_duration_seconds_bucket[5m]))) // GOOD. |
official-vendor-doc |
Prometheus classic histogram을 여러 replica에 걸쳐 percentile 집계할 때 | native histogram에는 다른 구문 사용 (sum(rate(...)) without by (le)) |
| PROM-HIST-C4 | Summary는 집계가 필요 없는 경우에만 사용을 고려해야 한다 | [§Rules of thumb] "Only if aggregation isn't needed, you can start thinking about summaries." | official-vendor-doc |
metric type 선택 시점 — 분산 시스템에서 횡단 집계 필요 여부 판단 | Summary 자체가 나쁘다는 뜻이 아님 — 단일 인스턴스·집계 불필요 시에는 정확도 높음 |
| PROM-HIST-C5 | 공식 최우선 권장: native histogram을 사용할 수 있으면 classic histogram과 Summary 모두보다 native histogram을 선호해야 한다 | [§Introduction] "If you can, use native histograms and prefer them over both classic histograms and summaries." | official-vendor-doc |
Prometheus 및 호환 클라이언트 라이브러리가 native histogram을 지원하는 환경 | native histogram 미지원 환경(older Prometheus, 일부 instrumentation library)에는 적용 불가 |
Usage Boundaries / 적용 경계
-
이 자료가 직접 증명하는 것:
PROM-HIST-C1,PROM-HIST-C2: Summary quantile을 avg()로 집계하면 통계적으로 틀린 값이 나온다는 Prometheus 공식 경고 — D9 결정의 핵심 근거PROM-HIST-C3: classic histogram에서 올바른 multi-instance percentile 집계 PromQL 구문PROM-HIST-C4: Summary 선택 조건 — "집계가 필요 없을 때만"PROM-HIST-C5: native histogram 최우선 권장
-
이 자료가 증명하지 않는 것:
- Micrometer의
publishPercentiles()vspublishPercentileHistogram()동작 차이 (별도 Micrometer 문서 필요) - ca-tmpl의 Spring Boot + Micrometer 환경에서 histogram 버킷이 실제로 Prometheus로 노출되는지 (
locally-verified미달) - native histogram이 Micrometer + Spring Boot 3 조합에서 지원되는지 여부
- 정확한 버킷 경계값 선택 방법 (SLO-driven 설계는 별도 문서)
- Micrometer의
-
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl에서
publishPercentileHistogram(true)설정 시 Prometheus exposition 형식 확인 (actuator/prometheus응답) - native histogram이 현재 사용 중인 Micrometer 버전에서 지원되는지 여부
- ca-tmpl에서
메모 / Notes
- Prometheus 공식 문서는
avg(metric{quantile="X"})를 BAD 패턴으로 명시 — D9에서 "client-side percentiles는 인스턴스 간 집계 불가"라는 경고와 직접 대응 - native histogram preference(PROM-HIST-C5)는 Micrometer 문서(
MM-HIST-C4)의publishPercentileHistogram권장과 방향 일치 — 추가 raw source로 cross-reference 가능 - classic histogram의 올바른 집계 구문(
sum by (le))은 D9 구현 시 PromQL 작성 기준으로 직접 사용 가능
Related / 관련
- 같은 주제 다른 official-doc: raw/official-docs/metric-micrometer-histogram-percentile-concepts — Micrometer publishPercentiles vs publishPercentileHistogram 비교
- 같은 주제 다른 official-doc: raw/official-docs/metric-prometheus-label-cardinality-best-practices — D8 cardinality bounds 근거
- 이 자료를 인용한 branch-note: raw/branch-notes/feature-metrics-alerting-contract