llm-wiki/vault/20-evidence/official-docs/metric-micrometer-histogram-percentile-concepts.md

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title	source_type	url	archive_url	related_branches	related_projects	tags	created
Micrometer — Histograms and Percentiles (Concepts Reference)	official-doc	https://docs.micrometer.io/micrometer/reference/concepts/histogram-quantiles.html		feature-metrics-alerting-contract	ca-skeleton	official-doc ca-skeleton metrics observability micrometer histogram percentile	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]] (생성 시)