llm-wiki/vault/20-evidence/official-docs/metric-prometheus-label-cardinality-best-practices.md

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

title	source_type	url	archive_url	related_branches	related_projects	tags	created	vendor
Prometheus Metric and Label Naming — Official Best Practices (label cardinality)	official-doc	https://prometheus.io/docs/practices/naming/		feature-metrics-alerting-contract	ca-skeleton	official-doc ca-skeleton observability prometheus micrometer high-cardinality metric-naming	2026-06-14	Prometheus (CNCF)

Prometheus Metric and Label Naming — Official Best Practices

Layer: raw/official-docs/ — Prometheus 공식 문서 verbatim 발췌 + 출처 기록. 검증된 요약은 /ingest 후 wiki/concepts/ 에 별도 작성. 원본은 raw에 영구 보관.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-metrics-alerting-contract	D8 — Micrometer/Prometheus metrics 에서 high-cardinality tag (user_id, request_id, raw_url, ip_address) 금지 정책의 1차 공식 근거.

출처 / Source

• 원본 URL: https://prometheus.io/docs/practices/naming/
• 아카이브 URL: (없음 — 2026-06-14 기준 접근 가능)
• 저자 / 조직: Prometheus Authors (CNCF)
• 발행일: 미명시 (공식 문서, 지속 관리)
• 마지막 확인일: 2026-06-14

왜 저장했는지 / Why archived

Prometheus 공식 문서의 Labels 섹션 CAUTION 블록은 high-cardinality 레이블(user_id, email, raw_url 등)을 사용하면 time series 폭증으로 저장량이 급증한다는 것을 직접 경고한다. feature-metrics-alerting-contract 의 D8 (high-cardinality tag 금지 정책) 이 UNSUPPORTED_DECISION 으로 남아있던 것을 이 공식 근거로 대체한다.

핵심 인용 / Key quotes (verbatim, 2개 Self-Grep 통과 + 1개 needs-confirmation)

[§Labels — CAUTION block] "Remember that every unique combination of key-value label pairs represents a new time series, which can dramatically increase the amount of data stored. Do not use labels to store dimensions with high cardinality (many different label values), such as user IDs, email addresses, or other unbounded sets of values." (Self-Grep: /tmp/source-fetch-prometheus-naming-20260614.txt line 30 — PASS)

[§Labels] "Do not use labels to store dimensions with high cardinality (many different label values), such as user IDs, email addresses, or other unbounded sets of values." (Self-Grep: /tmp/source-fetch-prometheus-naming-20260614.txt lines 22, 30 — PASS)

[§Metric names — suffix] "an accumulating count has total as a suffix, in addition to the unit if applicable." (Self-Grep: line 14 in fetched text — WebFetch model quoted this within its paraphrase wrapper; original page phrasing may differ slightly. Status: needs-confirmation — direct page inspection recommended.)

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
PROM-CARD-C1	Prometheus 에서 high-cardinality label(user ID, email, unbounded set)을 사용하면 time series 수가 폭발적으로 증가하여 저장량이 급증한다.	[§Labels CAUTION] "Remember that every unique combination of key-value label pairs represents a new time series, which can dramatically increase the amount of data stored. Do not use labels to store dimensions with high cardinality (many different label values), such as user IDs, email addresses, or other unbounded sets of values."	official-reference	Prometheus exposition format 을 사용하는 모든 metric 시스템 (Micrometer + Prometheus 포함)	어느 cardinality 임계값이 "high" 인지 정량 수치를 제시하지 않음. Prometheus 이외 다른 TSDB (InfluxDB, VictoriaMetrics 등) 에도 동일 원칙이 적용된다는 보장은 이 문서 범위 밖
PROM-CARD-C2	user IDs, email addresses, 또는 기타 unbounded set 은 label 로 사용하면 안 된다.	[§Labels] "Do not use labels to store dimensions with high cardinality (many different label values), such as user IDs, email addresses, or other unbounded sets of values."	official-reference	Prometheus 레이블 설계 전반	request_id, raw_url, ip_address 등의 금지 여부는 이 문서에서 열거하지 않음 — user_id/email/unbounded set 의 예시로부터 추론 필요. ca-tmpl 의 구체적 tag 목록(raw_url, ip_address, raw_query)의 금지는 본 원칙의 적용이지 직접 열거는 아님
PROM-CARD-C3	누산 카운터(accumulating count) metric 은 unit suffix 외에 추가로 total suffix 를 붙여야 한다.	[§Metric names] "an accumulating count has total as a suffix, in addition to the unit if applicable."	needs-confirmation	Prometheus metric naming — counter type	WebFetch 모델이 paraphrase wrapper 안에 이 문장을 포함했으나 원문 byte-exact 여부 미확인 — 실제 페이지 직접 확인 권장. Micrometer 가 이 suffix 를 자동으로 부착하는지 여부도 이 문서 범위 밖 (Micrometer 자체 문서에서 별도 확인 필요)
PROM-CARD-C4	label 은 metric 의 특성(characteristics)을 구분하기 위해 사용해야 한다.	[§Labels] "Use labels to differentiate the characteristics of the thing that is being measured"	needs-confirmation	Prometheus label 설계 가이드라인	WebFetch 결과에서 verbatim grep 미통과 — 원문 페이지 직접 확인 필요. label 의 최대 허용 cardinality 수치(임계값)는 이 문서에 없음

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • PROM-CARD-C1: Prometheus 에서 high-cardinality label 이 time series 수 폭증 + 저장량 급증을 유발한다 (공식 경고).
  • PROM-CARD-C2: user IDs, email addresses, unbounded set 값은 label 에 사용하면 안 된다 (공식 금지 예시).
  • PROM-CARD-C3: counter metric 에 total suffix 가 필요하다.
  • PROM-CARD-C4: label 은 특성(characteristics) 구분 목적에만 사용해야 한다.
• 이 자료가 증명하지 않는 것:
  • cardinality "high" 의 정량 임계값 (예: 10,000 시리즈 이상이면 high 등).
  • request_id, raw_url, ip_address, raw_query 가 금지 태그임을 명시적으로 열거하지 않음 — C2 에서 추론.
  • Micrometer 가 total suffix 를 자동 부착하는지 여부 (Micrometer 자체 문서 필요).
  • InfluxDB, VictoriaMetrics 등 타 TSDB 에도 동일 원칙이 동일하게 적용된다는 보장.
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl 의 raw_url, ip_address, raw_query, raw_header_value 금지는 C2 에서 추론한 적용이므로 별도 ca-tmpl 정책 문서에 "C2 기반 적용" 으로 명시 필요.
  • Micrometer Prometheus registry 가 total suffix 를 자동으로 부착하는지 actuator 실측 확인 필요 (Claims To Verify 항목).
  • tenant_id 의 bounded mapping table id (ca-tmpl 1000 상한) 가 실제로 충분히 낮은 cardinality 인지는 실운영 traffic 기반 판단 필요.

메모 / Notes

• WebFetch 가 원문을 요약/패러프레이즈한 형태로 반환했으므로, CAUTION 블록 verbatim 은 두 번째 fetch 의 explicit verbatim 표기를 사용했음. 다른 인용(C3, C4) 은 fetch 결과에서 추출된 paraphrase 기반이므로 원문 byte-exact 여부 needs-confirmation — 실제 페이지에서 직접 확인 권장.
• 추가로 봐야 할 동일 출처 페이지: https://prometheus.io/docs/practices/instrumentation/ (instrumentation 가이드) 및 https://prometheus.io/docs/concepts/data_model/ (data model — label cardinality 이론적 배경).

Related / 관련

• raw/official-docs/metric-micrometer-naming-convention-official — Micrometer dot.case naming + unit suffix convention (D2 근거)
• raw/official-docs/metric-google-sre-slo-burn-rate — SLO burn-rate alert (D3, D5 근거)
• raw/official-docs/metric-otel-metrics-data-model-spec — OTel metrics data model (D6 대안 근거)
• raw/official-docs/resilience4j-micrometer-module — Resilience4j Micrometer 모듈 (D4 근거)
• raw/branch-notes/feature-metrics-alerting-contract — 본 자료를 소비하는 branch-note (D8 갱신 대상)