Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

10 KiB

Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed

title

source_type

url

archive_url

status

confidence

OpenTelemetry Metrics Data Model & Semantic Conventions

Layer: raw/official-docs/ — OpenTelemetry Metrics Data Model spec verbatim. ca-tmpl 의 Micrometer + Prometheus 채택 대안으로 OTel direct metrics 평가의 1차 spec 근거.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-metrics-alerting-contract	metrics SDK 선택 (Micrometer + Prometheus default vs OpenTelemetry direct) 비교 시 OTel data model 의 vendor-neutral 변환 보장 spec 근거
raw/project-notes/ca-skeleton-operational-contract	§18. Control Plane Contract (Metrics / Alerting) 의 SDK 대안 비교 (Group G-A 대안 2 — OpenTelemetry metrics vs Micrometer + Prometheus)

컨텍스트

ca-tmpl 이 Micrometer + Prometheus 를 채택한 대안으로 OpenTelemetry metrics 를 직접 채택할 때의 spec / naming / attribute 비교의 1차 근거.

출처 / Source

원본 URL: https://opentelemetry.io/docs/specs/otel/metrics/data-model/
아카이브 URL: (미수집)
저자 / 조직: OpenTelemetry Authors (CNCF)
발행일: rolling spec
마지막 확인일: 2026-05-27

핵심 인용 / Key quotes (verbatim)

[§Overview] "Popular existing metrics data formats can be unambiguously translated into the OpenTelemetry data model for metrics, without loss of semantics or fidelity."

[§Overview — Prometheus translation] "The data model can be unambiguously translated into the Prometheus Remote Write protocol without loss of features or semantics, through well-defined translations of the data."

[§Instruments — reference to API] "The exact OpenTelemetry instruments are detailed in the API specification."

[§Events => Data Stream => Timeseries] "one instrument can transform events into more than one type of metric stream."

[§Sums — monotonic flag] "A flag denoting whether the Sum is monotonic. In this case of metrics, this means the sum is nominally increasing, which we assume without loss of generality."

[§Sums — delta monotonic] "For delta monotonic sums, this means the reader SHOULD expect non-negative values."

[§Sums — cumulative monotonic] "For cumulative monotonic sums, this means the reader SHOULD expect values that are not less than the previous value."

[§Events => Data Stream => Timeseries] "Spatial reaggregation: Metrics that are produced with unwanted attributes can be re-aggregated into metrics having fewer attributes."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
OTEL-MET-C1	기존 인기 metrics 데이터 포맷은 의미 / fidelity 손실 없이 OTel 데이터 모델로 명확하게 (unambiguously) 변환 가능	[§Overview] "Popular existing metrics data formats can be unambiguously translated into the OpenTelemetry data model for metrics, without loss of semantics or fidelity."	`official-standard`	Prometheus / StatsD 등 기존 포맷 → OTLP 변환	"모든" 포맷이 손실 없이 변환된다는 강한 결론 아님 — "popular existing" 한정
OTEL-MET-C2	OTel 데이터 모델은 Prometheus Remote Write 프로토콜로 well-defined translation 을 통해 의미 / 기능 손실 없이 변환 가능	[§Overview — Prometheus translation] "The data model can be unambiguously translated into the Prometheus Remote Write protocol without loss of features or semantics, through well-defined translations of the data."	`official-standard`	OTel → Prometheus Remote Write 변환	Prometheus scrape (pull) 형식과의 변환이 동일하게 손실 없다는 뜻 아님 — Remote Write 한정
OTEL-MET-C3	하나의 instrument 가 여러 종류의 metric stream 으로 events 를 변환 가능	[§Events => Data Stream => Timeseries] "one instrument can transform events into more than one type of metric stream."	`official-standard`	OTel instrument → metric stream 매핑	instrument 의 정확한 종류 (Counter / UpDownCounter / Histogram / Gauge / Observable*) 의 enumeration 은 본 페이지가 아닌 API spec 에 위임 (`OTEL-MET-C4`)
OTEL-MET-C4	정확한 OTel instruments enumeration 은 API specification 에서 별도 정의 — Data Model spec 은 instrument enumeration 을 직접 다루지 않음	[§Instruments — reference to API] "The exact OpenTelemetry instruments are detailed in the API specification."	`official-standard`	Data Model spec 의 범위 한정	Counter / Histogram / Gauge 같은 구체 instrument 의 정의는 본 spec 으로 직접 증명 불가 — API spec 별도
OTEL-MET-C5	Sum 의 monotonic flag: 단조 증가 (nominally increasing). Delta monotonic 은 non-negative values 기대, Cumulative monotonic 은 이전 값 이상 기대	[§Sums — monotonic flag] "A flag denoting whether the Sum is monotonic. ... nominally increasing" + [§Sums — delta monotonic] "For delta monotonic sums, this means the reader SHOULD expect non-negative values." + [§Sums — cumulative monotonic] "For cumulative monotonic sums, this means the reader SHOULD expect values that are not less than the previous value."	`official-standard`	Sum 타입 metric 의 reader 측 기대값	reset 발생 시 (예: process restart) 의 처리 정책은 본 인용에 명시 없음
OTEL-MET-C6	unwanted attribute 가 포함된 metric 은 spatial reaggregation 으로 더 적은 attribute 의 metric 으로 재집계 가능	[§Events => Data Stream => Timeseries] "Spatial reaggregation: Metrics that are produced with unwanted attributes can be re-aggregated into metrics having fewer attributes."	`official-standard`	후처리 단계의 attribute drop / aggregation	high-cardinality attribute 가 자동으로 제거된다는 뜻 아님 — 명시적 reaggregation 설정 필요. "should be avoided" 같은 강한 정책 표현은 본 인용에 없음
OTEL-MET-C7	`http.server.request.duration` semantic convention 의 required attributes (`http.request.method`, `http.response.status_code`, `http.route` 등)	(본 페이지 발췌에 명시 없음 — HTTP semantic conventions 별도 페이지)	`needs-confirmation`	HTTP server metric 의 attribute 표준	본 Data Model spec 페이지에는 HTTP semantic convention 의 구체 attribute 가 포함되지 않음 — `docs/specs/semconv/http/http-metrics/` 별도 페이지 필요

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- OTEL-MET-C1, C2: OTel data model 의 vendor-neutral 변환 (Prometheus Remote Write 포함) 보장
- OTEL-MET-C3, C4: instrument 의 multi-stream 변환 + instrument enumeration 은 API spec 위임
- OTEL-MET-C5: Sum 의 monotonic 의미와 delta/cumulative reader 기대값
- OTEL-MET-C6: spatial reaggregation 으로 attribute reduce 가능
이 자료가 증명하지 않는 것:
- OTEL-MET-C7: http.server.request.duration 같은 구체 semantic convention name + required attributes (http.request.method/http.response.status_code/http.route) — 별도 semconv 페이지
- high-cardinality attribute 가 "SHOULD be avoided" 라는 강한 정책 표현 — 본 페이지는 reaggregation 가능성만 직접 지지
- OTel Histogram 의 exponential bucket / exemplar 같은 신규 개념 (별도 페이지)
- Spring Boot 3 + Micrometer 가 OTel naming 으로 자동 정합한다는 결론 (Micrometer OTLP bridge 별도 reference)
- OTel direct 채택이 Micrometer + Prometheus 보다 우월하다는 결론 — vendor-neutrality 와 ecosystem 성숙도의 trade-off
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 Spring Boot 3 default meter (http.server.requests) 와 OTel semconv (http.server.request.duration) 의 name 충돌 시 매핑 전략
- Micrometer tag 이름 (method/status/uri) 과 OTel attribute (http.request.method/http.response.status_code/http.route) 의 변환 책임 (Micrometer OTLP bridge 인지 별도 mapper)
- OTel exporter 채택 시 Prometheus scrape 모델 (pull) → OTLP push 변환의 운영 영향

메모 / Notes (내 프로젝트 해석)

본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

naming 비교:
- OTel: http.server.request.duration (dot + singular) — 본 페이지 직접 인용 아님, semconv 별도.
- Micrometer: http.server.requests (dot + plural).
- Spring Boot Actuator default 는 Micrometer 명명을 따름. OTel naming 은 일부 동일, 일부 다름.
attribute (tag) 정합 (semconv 별도 페이지 기반 추론):
- OTel http.request.method / http.response.status_code / http.route
- Micrometer (Spring) method / status / uri
- ca-tmpl Metric Defaults 는 Micrometer naming (method/status/uri-template) 에 가까움 — uri_template = OTel http.route 와 의미 일치.
장점:
- vendor-neutral OTLP exporter → Prometheus / Datadog / New Relic / Honeycomb 동일 spec (OTEL-MET-C1, C2).
- semantic conventions 가 cross-language (Java/Go/Python) 통일.
- tracing 과 같은 SDK / transport 공유.
단점:
- Spring Boot 3 는 Micrometer default. OTel direct 채택 시 bridge 필요.
- histogram bucket 정책이 OTLP exemplar / exponential histogram 등 신규 개념 추가됨 → Prometheus scrape 단순화 model 과 차이.
ca-tmpl 과의 차이:
- ca-tmpl 은 Micrometer + Prometheus scrape 를 default 로 둠. OTel metrics 는 채택 안 함.
- 그러나 Micrometer OTLP registry 사용 시 OTel exporter 로 swap 가능 (naming 은 변환됨).

같은 주제 다른 raw:
- raw/official-docs/metric-micrometer-naming-convention-official (Micrometer naming, 비교 대상)
- raw/official-docs/metric-google-sre-slo-burn-rate (alerting 정책, 별도 spec)
인용하는 branch:
- raw/branch-notes/feature-metrics-alerting-contract
인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract (§18 Metrics / Alerting — SDK 대안 비교)
인용한 wiki 요약: (미작성)

10 KiB Raw Blame History