8.2 KiB
title, source_type, url, archive_url, related_branches, related_projects, tags, created
| title | source_type | url | archive_url | related_branches | related_projects | tags | created | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| OpenTelemetry Versioning and Stability Specification | official-doc | https://opentelemetry.io/docs/specs/otel/versioning-and-stability/ |
|
|
|
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 공식 문서:
- 이 자료를 인용한 branch: raw/branch-notes/feature-contract-registry-governance
- wiki 요약 (생성 시):
[[wiki/concepts/opentelemetry-versioning-stability]]