119 lines
10 KiB
Markdown
119 lines
10 KiB
Markdown
---
|
|
title: OpenTelemetry Metrics Data Model & Semantic Conventions
|
|
source_type: official-doc
|
|
url: https://opentelemetry.io/docs/specs/otel/metrics/data-model/
|
|
archive_url:
|
|
status: raw
|
|
confidence: high
|
|
tags: [ca-metrics-alerting, opentelemetry, metrics, semantic-conventions, data-model, official-doc]
|
|
related_projects: [ca-skeleton-operational-contract]
|
|
related_branches: [feature-metrics-alerting-contract]
|
|
created: 2026-05-22
|
|
last_reviewed: 2026-05-27
|
|
---
|
|
|
|
# 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 은 변환됨).
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 다른 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 요약: (미작성)
|