---
title: "OpenTelemetry Versioning and Stability Specification"
source_type: official-doc
url: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/
archive_url:
related_branches: [feature-contract-registry-governance]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, observability, opentelemetry, span-event, trace-status]
created: 2026-06-15
---

# OpenTelemetry Versioning and Stability Specification

> Layer: `raw/` — 외부 자료(공식 문서)의 원문 발췌·출처 기록.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-contract-registry-governance]] | D5: 외부 platform 표준(예: OpenTelemetry semantic conventions)을 쓰는 경우에도 skeleton registry에 per-token mapping row를 남긴다 — OTel semantic conventions는 experimental→stable 전환 및 rename이 발생하며, 이를 schema file로 기술해야 하므로 registry mapping row가 없으면 breaking change를 추적할 수 없다 |

## 출처 / Source

- 원본 URL: https://opentelemetry.io/docs/specs/otel/versioning-and-stability/
- 아카이브 URL: (미수집)
- 저자 / 조직: OpenTelemetry Authors
- 발행일: (페이지 갱신 지속; 확인일 기준 유효)
- 마지막 확인일: 2026-06-15

## 왜 저장했는지 / Why archived

OpenTelemetry semantic conventions는 Development(experimental) → Stable 전환 사이클에서 rename·breaking change가 발생하며, 모든 변경은 Schema File에 기술해야 한다. 이것이 skeleton registry의 외부 표준 매핑 row(D5) 필요성의 공식 근거다.

## 핵심 인용 / Key quotes (verbatim, 5개)

> [§Signal Lifecycle — Development] "While signals are in development, breaking changes and performance issues MAY occur."

> [§Signal Lifecycle — Development] "Long-term dependencies SHOULD NOT be taken against signals in Development."

> [§Signal Lifecycle — Stable] "Once a signal in Development has gone through rigorous testing, it MAY transition to Stable. Long-term dependencies MAY now be taken against this signal."

> [§Signal Lifecycle — Stable] "All existing API calls MUST continue to compile and function against all future minor versions of the same major version."

> [§Telemetry Stability] "Changes to telemetry produced by OpenTelemetry instrumentation SHOULD avoid breaking analysis tools, such as dashboards and alerts."

> [§Telemetry Stability — Schema] "All such changes MUST be described in the OpenTelemetry Schema File Format and published in this repository."

> [§Semantic Conventions] "Semantic Conventions defines breaking changes as those that would break the common usage of tooling written against the telemetry it produces."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| OTEL-VS-C1 | Development 단계 신호(signal)에는 breaking changes and performance issues MAY occur — 장기 의존 금지 | [§Signal Lifecycle — Development] "While signals are in development, breaking changes and performance issues MAY occur." / "Long-term dependencies SHOULD NOT be taken against signals in Development." | `official-standard` | OpenTelemetry API/SDK/Semantic Conventions 중 Development(experimental) 상태인 모든 신호 | 특정 semantic convention 항목이 현재 Development 상태인지 여부 (개별 항목 상태는 해당 convention 문서 확인 필요) |
| OTEL-VS-C2 | Stable 단계로 전환된 신호는 장기 의존이 허용되며, 동일 major version 내 모든 미래 minor version에서 기존 API call이 compile·동작해야 한다 | [§Signal Lifecycle — Stable] "Long-term dependencies MAY now be taken against this signal." / "All existing API calls MUST continue to compile and function against all future minor versions of the same major version." | `official-standard` | OpenTelemetry Stable 상태 신호 | Stable 전환 이후에도 major version bump 시 breaking change가 없다는 보장은 아님 |
| OTEL-VS-C3 | OTel instrumentation이 생성하는 telemetry 변경은 대시보드·알림 같은 분석 도구를 깨뜨리지 않아야 한다(SHOULD) | [§Telemetry Stability] "Changes to telemetry produced by OpenTelemetry instrumentation SHOULD avoid breaking analysis tools, such as dashboards and alerts." | `official-standard` | OpenTelemetry instrumentation을 사용하는 모든 프로젝트 | "SHOULD"이므로 절대적 금지가 아닌 강한 권고. 불가피한 breaking change가 완전히 금지되지는 않음 |
| OTEL-VS-C4 | telemetry에 대한 모든 breaking change·rename은 OpenTelemetry Schema File Format에 기술하고 저장소에 게시해야 한다(MUST) | [§Telemetry Stability — Schema] "All such changes MUST be described in the OpenTelemetry Schema File Format and published in this repository." | `official-standard` | OpenTelemetry telemetry schema 변경 전체 (semantic convention rename, attribute 제거 등) | 개별 사용자 프로젝트가 Schema File을 직접 작성해야 한다는 의미가 아님 — OTel 저장소 관리자의 의무 |
| OTEL-VS-C5 | Semantic Conventions의 breaking change는 "생성된 telemetry 기반 tooling의 common usage를 깨뜨리는 변경"으로 정의되며, schema file로 기술 가능한 변경에 한해 허용된다 | [§Semantic Conventions] "Semantic Conventions defines breaking changes as those that would break the common usage of tooling written against the telemetry it produces." / "Changes to semantic conventions in this specification are allowed, provided that the changes can be described by schema files." | `official-standard` | OTel Semantic Conventions 버전 관리 — 특히 attribute rename, metric name 변경 등 | schema file로 기술 불가능한 변경이 실제로 어떤 종류인지는 이 문서만으로 확정 불가 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `OTEL-VS-C1`: OTel experimental/Development 신호는 언제든 breaking change가 가능 → skeleton이 OTel experimental convention을 직접 의존하면 안 됨
  - `OTEL-VS-C4`: OTel semantic conventions의 rename·breaking change는 Schema File에 공식 기록됨 → skeleton registry mapping row가 있으면 Schema File 변경을 추적 지점으로 활용 가능
  - `OTEL-VS-C5`: OTel semantic conventions는 정의된 breaking change 기준과 schema file 제약 하에서 변경 허용 → convention 버전이 올라가면 기존 metric/log field 이름이 바뀔 수 있음
- 이 자료가 증명하지 않는 것:
  - skeleton 프로젝트가 OTel Schema File을 직접 작성·유지해야 한다는 의무 (OTel 저장소 측 의무)
  - mapping row의 구체적인 column schema 또는 형식 (D4 UNSUPPORTED_DECISION 영역)
  - 특정 semantic convention 항목(예: `http.method`)이 현재 Development/Stable 중 어느 상태인지
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl이 사용하는 구체적인 OTel semantic convention 항목의 stability status 확인 (해당 convention 문서 개별 확인 필요)
  - OTel Schema File의 실제 변경 이력과 ca-tmpl registry의 mapping row 연동 방식 PoC

## 메모 / Notes

- OTel specification은 API/SDK/Semantic Conventions가 독립적인 버전 번호를 가짐 — "OTel 버전 X" 하나로 모든 안정성을 가정하면 안 됨
- Semantic Conventions의 experimental→stable 전환은 단순 버전 bump가 아니라 spec 내 명시적 stability marker 변경으로 추적 가능
- D5 결정의 motivating risk: OTel semantic conventions에서 `http.method` → `http.request.method` 같은 rename이 실제 발생했음 — registry mapping row 없이 hardcoding하면 alert dashboard 등에서 silent break 발생

## Related / 관련

- 같은 주제 OTel 공식 문서:
  - [[raw/official-docs/tracing-otel-trace-api-spec]]
  - [[raw/official-docs/log-otel-log-data-model-spec]]
  - [[raw/official-docs/metric-otel-metrics-data-model-spec]]
- 이 자료를 인용한 branch: [[raw/branch-notes/feature-contract-registry-governance]]
- wiki 요약 (생성 시): `[[wiki/concepts/opentelemetry-versioning-stability]]`