89 lines
6.9 KiB
Markdown
89 lines
6.9 KiB
Markdown
---
|
|
title: "Prometheus — Histograms and Summaries Practices"
|
|
source_type: official-doc
|
|
url: https://prometheus.io/docs/practices/histograms/
|
|
archive_url:
|
|
related_branches: [feature-metrics-alerting-contract]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, observability, prometheus, histogram-quantile, percentile-aggregation]
|
|
created: 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()` vs `publishPercentileHistogram()` 동작 차이 (별도 Micrometer 문서 필요)
|
|
- ca-tmpl의 Spring Boot + Micrometer 환경에서 histogram 버킷이 실제로 Prometheus로 노출되는지 (`locally-verified` 미달)
|
|
- native histogram이 Micrometer + Spring Boot 3 조합에서 지원되는지 여부
|
|
- 정확한 버킷 경계값 선택 방법 (SLO-driven 설계는 별도 문서)
|
|
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- ca-tmpl에서 `publishPercentileHistogram(true)` 설정 시 Prometheus exposition 형식 확인 (`actuator/prometheus` 응답)
|
|
- native histogram이 현재 사용 중인 Micrometer 버전에서 지원되는지 여부
|
|
|
|
## 메모 / 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]]
|