---
title: "Micrometer — Histograms and Percentiles (Concepts Reference)"
source_type: official-doc
url: https://docs.micrometer.io/micrometer/reference/concepts/histogram-quantiles.html
archive_url:
related_branches: [feature-metrics-alerting-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, metrics, observability, micrometer, histogram, percentile]
created: 2026-06-14
---

# Micrometer — Histograms and Percentiles (Concepts Reference)

> Layer: `raw/official-docs/` — Micrometer 공식 레퍼런스에서 histogram / percentile 설정 전략을 발췌·보관.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-metrics-alerting-contract]] | D9 — latency timer 의 percentile/histogram 게시 전략 (`publishPercentiles` vs `publishPercentileHistogram` vs `serviceLevelObjectives`). 특히 client-side percentiles 가 dimension 간 집계 불가하다는 caveat. |

## 출처 / Source

- 원본 URL: https://docs.micrometer.io/micrometer/reference/concepts/histogram-quantiles.html
- 아카이브 URL: (미등록 — 접근 시 archive.org 스냅샷 권장)
- 저자 / 조직: Micrometer Project (VMware / Spring 에코시스템)
- 발행일: (미명시 — Micrometer 공식 reference, 버전별 갱신)
- 마지막 확인일: 2026-06-14

## 왜 저장했는지 / Why archived

`feature-metrics-alerting-contract` 의 D9 결정 (`publishPercentiles(0.5, 0.9, 0.95, 0.99)`) 이 UNSUPPORTED_DECISION 으로 표시되어 있었음. Micrometer 공식 reference 가 `publishPercentiles` / `publishPercentileHistogram` / `serviceLevelObjectives` 세 전략의 차이 — 특히 client-side percentile 의 dimension 간 집계 불가 caveat — 를 직접 설명하므로, D9 의 1차 근거 자료로 보관.

## 핵심 인용 / Key quotes (verbatim, Self-Grep 통과 4개)

> [§Percentile histograms] "Micrometer accumulates values to an underlying histogram and ships a predetermined set of buckets to the monitoring system."

> [§Percentile histograms] "If you target Prometheus, Atlas, or Wavefront, prefer this approach, since you can aggregate the histograms across dimensions."

> [§Client-side percentiles] "Micrometer computes a percentile approximation for each meter ID (set of name and tags) and ships the percentile value to the monitoring system."

> [§Aggregation note] "For those monitoring systems, where percentiles can be approximated using the histogram, it is usually unnecessary to also publish client-side percentiles since in those scenarios client-side percentiles are redundant and also non-aggregable across dimensions."

---

**Self-Grep 검증 기록:**

아래 4개 인용은 WebFetch 결과물(`/tmp/source-fetch-micrometer-1718323200.txt`)에서 grep -nF 로 직접 확인됨.

- Quote A (Micrometer accumulates...): line 5 ✓
- Quote B (If you target Prometheus...): line 5 ✓
- Quote C (Micrometer computes a percentile approximation...): line 7 ✓
- Quote D (For those monitoring systems...): line 23 ✓

**Discarded (NOT self-grep verified):** 사용자가 요청한 3개 인용 — "Used to publish percentile values computed in your application. These values are non-aggregable across dimensions.", "Used to publish a histogram suitable for computing aggregable...", "Used to publish a cumulative histogram with buckets defined by your SLOs." — 은 WebFetch 결과에서 paraphrase 로만 등장하여 verbatim 확인 불가. 본 파일에서 제외. 원문 페이지에는 존재하는 것으로 추정되나(Javadoc API 설명 형식) 본 fetch 회차에서 증명되지 않음 → Claim 에 반영 시 `needs-confirmation` 표시.

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| MM-HIST-C1 | Micrometer 의 percentile histogram 방식은 값을 내부 히스토그램에 누적한 뒤 사전 정의 bucket 셋을 모니터링 시스템으로 전송한다 | [§Percentile histograms] "Micrometer accumulates values to an underlying histogram and ships a predetermined set of buckets to the monitoring system." | `official-vendor-doc` | Micrometer 를 사용하는 모든 Spring/JVM 애플리케이션 | bucket 수·범위·기본 clamping 값이 얼마인지는 본 인용에서 직접 명시되지 않음 |
| MM-HIST-C2 | Prometheus, Atlas, Wavefront 를 사용하는 경우 percentile histogram 방식을 권장한다. 이유는 histogram 을 dimension 간 집계할 수 있기 때문이다 | [§Percentile histograms] "If you target Prometheus, Atlas, or Wavefront, prefer this approach, since you can aggregate the histograms across dimensions." | `official-vendor-doc` | Prometheus / Atlas / Wavefront 를 백엔드로 사용하는 서비스 | 다른 모니터링 백엔드(CloudWatch, Datadog 등)에서도 동일하게 적용된다는 보장 없음 |
| MM-HIST-C3 | Client-side percentile 방식은 meter ID(이름 + 태그 조합)별로 percentile 근사값을 계산한 뒤 그 값을 모니터링 시스템으로 전송한다 | [§Client-side percentiles] "Micrometer computes a percentile approximation for each meter ID (set of name and tags) and ships the percentile value to the monitoring system." | `official-vendor-doc` | 모든 Micrometer 지원 모니터링 시스템 (server-side percentile 지원 여부 무관) | client-side percentile 이 histogram-based 방식과 동시 사용 가능한지, 정확도 차이가 어느 정도인지 본 인용으로 알 수 없음 |
| MM-HIST-C4 | Histogram 기반 percentile 계산을 지원하는 모니터링 시스템에서는 client-side percentile 을 동시에 게시하는 것이 불필요하다. client-side percentile 은 해당 시나리오에서 중복이며 dimension 간 집계가 불가하다 | [§Aggregation note] "For those monitoring systems, where percentiles can be approximated using the histogram, it is usually unnecessary to also publish client-side percentiles since in those scenarios client-side percentiles are redundant and also non-aggregable across dimensions." | `official-vendor-doc` | Prometheus / Atlas / Wavefront + `publishPercentileHistogram()` 동시 사용 환경 | `publishPercentiles` 단독 사용 시의 집계 제한 범위. 단지 "불필요"이지 기능적으로 오작동한다는 의미는 아님 |
| MM-HIST-C5 | `publishPercentiles`, `publishPercentileHistogram`, `serviceLevelObjectives` 는 Timer builder 에서 동시 구성 가능한 별도 설정 메서드다 | [§Configuration example] Timer.builder("my.timer").publishPercentiles(0.5, 0.95).publishPercentileHistogram().serviceLevelObjectives(Duration.ofMillis(100))... | `official-vendor-doc` | Micrometer Timer / DistributionSummary | 세 설정 조합 시 중복 metric 이 얼마나 생성되는지, 비용(시계열 수)이 어떤지는 본 예시만으로 판단 불가 |
| MM-HIST-C6 | `publishPercentiles` 방식은 애플리케이션 내에서 계산된 percentile 값을 게시하며, 이 값은 dimension 간 집계가 불가하다 (unverified — WebFetch paraphrase 에서만 확인, verbatim 미검증) | [§publishPercentiles bullet — paraphrase] "publishes non-aggregable percentile values computed in applications" | `needs-confirmation` | `publishPercentiles()` 를 사용하는 경우 | 본 fetch 에서 verbatim 확인 실패 — 원문 페이지 재방문 또는 Micrometer Javadoc 으로 대조 필요 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `MM-HIST-C1`: Micrometer histogram 방식이 bucket 을 모니터링 시스템으로 전송한다는 동작 방식
  - `MM-HIST-C2`: Prometheus/Atlas/Wavefront 사용 시 `publishPercentileHistogram()` 이 공식 권장 접근법임
  - `MM-HIST-C3`: `publishPercentiles()` 는 meter ID 단위 계산, 결과 값을 전송하는 방식
  - `MM-HIST-C4`: Histogram 지원 시스템에서 client-side percentile 동시 게시는 중복이며 dimension 간 집계 불가
  - `MM-HIST-C5`: 세 메서드가 동시 구성 가능한 Timer builder API 임
- 이 자료가 증명하지 않는 것:
  - 기본 bucket 수(73개/timer dimension, clamped 1ms~1min) — 본 fetch 에서 paraphrase 로만 등장, verbatim 미확인
  - `publishPercentileHistogram()` 이 Prometheus 에서 생성하는 정확한 time series 수 또는 scrape overhead
  - `serviceLevelObjectives()` 의 verbatim 정의("Used to publish a cumulative histogram with buckets defined by your SLOs.") — fetch 에서 paraphrase 처리됨, verbatim 미확인
  - Spring Boot auto-configuration 이 이 설정을 자동 활성화하는지 여부
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl 이 `publishPercentiles(0.5, 0.9, 0.95, 0.99)` 를 SLO-driven 으로 사용할 때 Prometheus 에서 실제로 얼마나 많은 time series 가 추가 생성되는지 (`actually-implemented` 등급 달성 전 필수)
  - `publishPercentileHistogram()` 전환 시 histogram_quantile 쿼리로 p99 집계가 dimension(uri_template) 단위로 정상 동작하는지 로컬 검증 필요
  - Micrometer Concepts/Timers 페이지(별도 fetch) 에서 bucket count default(73) 와 `minimumExpectedValue`/`maximumExpectedValue` 의 verbatim 확인 필요

## 메모 / Notes

- D9 는 이 자료 등록 전 `UNSUPPORTED_DECISION` 이었음. `MM-HIST-C2` + `MM-HIST-C4` 가 "Prometheus 를 쓴다면 `publishPercentileHistogram()` 을 선호하고, client-side percentile 은 dimension 집계 불가이므로 Prometheus 환경에서 단독 사용 시 집계 이점이 없다" 는 점을 공식 근거로 제공함 → D9 를 `UNSUPPORTED_DECISION → PARTIALLY_SUPPORTED` 로 갱신 가능. 단, `serviceLevelObjectives` 및 `publishPercentiles` 의 verbatim 정의는 추가 fetch 필요.
- WebFetch 가 Javadoc style 의 API 설명 bullet("Used to publish...") 을 paraphrase 처리한 것으로 보임. 해당 3개 인용은 `MM-HIST-C6` 을 `needs-confirmation` 으로 등록, 추후 원문 재확인 권장.
- 이 자료는 `official-vendor-doc` — company-tech-blog 와 혼동 금지. Micrometer 공식 reference 의 recommendation 은 best practice 근거로 사용 가능.

## Related / 관련

- 같은 주제 다른 official-doc: [[raw/official-docs/metric-micrometer-naming-convention-official]] (Micrometer naming convention)
- Histogram 응용: Prometheus `histogram_quantile` 공식 docs (별도 fetch 필요)
- Micrometer Concepts/Timers 페이지 — bucket count default, `minimumExpectedValue`/`maximumExpectedValue` verbatim 확인 위해 추가 fetch 권장
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/micrometer-histogram-percentile]]` (생성 시)