llm-wiki/raw/official-docs/opentelemetry-http-semconv-migration-guide.md

---
title: "HTTP Semantic Convention Stability Migration — OpenTelemetry Official Guide"
source_type: official-doc
url: https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/
archive_url:
related_branches: [feature-contract-registry-governance]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, observability, opentelemetry, metric-naming]
created: 2026-06-15
---

# HTTP Semantic Convention Stability Migration — OpenTelemetry Official Guide

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

## Parent / 활용 branch

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-contract-registry-governance]] | D5 — 외부 platform 표준(OpenTelemetry semantic conventions)을 쓰는 경우에도 skeleton registry에 mapping/version row를 남겨야 함을 증명. 토큰 이름 자체가 버전 간 변경(rename)된 실례이므로, mapping row 없이는 old vs new 이름 구분 불가. |

## 출처 / Source

- 원본 URL: https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/
- 아카이브 URL: (미수집)
- 저자 / 조직: OpenTelemetry Authors
- 발행일: (페이지 내 날짜 미표기 — v1.23.1 기준 가이드)
- 마지막 확인일: 2026-06-15

## 왜 저장했는지 / Why archived

OpenTelemetry HTTP semantic convention 이 v1.20.0 → v1.23.1(stable) 로 전환되면서 메트릭 이름(예: `http.server.duration` → `http.server.request.duration`), 단위(`ms` → `s`), 속성 키가 대규모로 변경되었다. 이는 외부 표준 토큰 이름이 실제로 rename 된 직접 증거로, `feature-contract-registry-governance` 의 D5 결정("외부 표준 사용 시 skeleton registry 에 mapping row 필수")을 정당화한다.

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

> [§도입부] "Due to the significant number of modifications and the extensive user base affected by them, existing HTTP instrumentations published by OpenTelemetry are required to implement a migration plan that will assist users in transitioning to the stable HTTP semantic conventions."

> [§도입부 — opt-in mechanism] "- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in their existing major version, which accepts:"

> [§HTTP server duration metric — Name] "- **Name**: `http.server.duration` → `http.server.request.duration`"

> [§HTTP client duration metric — Name] "- **Name**: `http.client.duration` → `http.client.request.duration`"

> [§HTTP client duration metric — Unit / §HTTP server duration metric — Unit] "- **Unit**: `ms` → `s`"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| OTEL-HM-C1 | OpenTelemetry HTTP semantic convention 전환은 "significant number of modifications"와 "extensive user base affected"를 근거로 structured migration plan을 의무화한다 | [§도입부] "Due to the significant number of modifications and the extensive user base affected by them, existing HTTP instrumentations published by OpenTelemetry are required to implement a migration plan" | `official-standard` | OpenTelemetry HTTP instrumentation을 채택한 모든 구현체 | 특정 언어/SDK가 이미 migration을 완료했는지 여부; ca-tmpl 특정 버전의 실제 준수 여부 |
| OTEL-HM-C2 | 서버 측 HTTP duration 메트릭 이름이 `http.server.duration` → `http.server.request.duration`으로 rename 되었다 | [§HTTP server duration metric] "- **Name**: `http.server.duration` → `http.server.request.duration`" | `official-standard` | OpenTelemetry HTTP server metrics를 사용하는 모든 instrumentation | old 이름이 특정 시점에 deprecated 처리된 날짜; SDK별 실제 전환 완료 여부 |
| OTEL-HM-C3 | 클라이언트 측 HTTP duration 메트릭 이름이 `http.client.duration` → `http.client.request.duration`으로 rename 되었다 | [§HTTP client duration metric] "- **Name**: `http.client.duration` → `http.client.request.duration`" | `official-standard` | OpenTelemetry HTTP client metrics를 사용하는 모든 instrumentation | SDK별 실제 전환 완료 여부; backward-compat 기간 |
| OTEL-HM-C4 | 두 duration 메트릭 모두 단위가 밀리초(`ms`) → 초(`s`)로 변경되었으며, 히스토그램 버킷 경계도 함께 조정되었다 | [§HTTP client/server duration metric] "- **Unit**: `ms` → `s`" | `official-standard` | `http.client.request.duration` 및 `http.server.request.duration` 메트릭 소비자 | 기존 대시보드/알림 쿼리의 자동 마이그레이션; Prometheus scrape 설정 변경 범위 |
| OTEL-HM-C5 | migration opt-in은 `OTEL_SEMCONV_STABILITY_OPT_IN` 환경변수로 제어하며, 값 `http`(stable만), `http/dup`(old+stable 동시), 미설정(old 유지) 세 가지 동작을 정의한다 | [§도입부] "- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in their existing major version, which accepts:" | `official-standard` | OTEL_SEMCONV_STABILITY_OPT_IN 를 인식하는 instrumentation 라이브러리 | ca-tmpl 프로젝트의 실제 환경변수 설정 여부; Java agent vs manual SDK 동작 차이 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `OTEL-HM-C1`: OpenTelemetry 자체가 "변경의 규모가 크고 영향받는 사용자 기반이 광범위하다"고 명시하여 structured migration을 의무화함
  - `OTEL-HM-C2` / `OTEL-HM-C3`: 메트릭 이름이 실제로 rename된 사실 — skeleton registry에 version/mapping row 없이는 old name vs new name 구분 불가
  - `OTEL-HM-C4`: 단위 변경(ms → s)은 대시보드·알림·SLO 쿼리에 breaking change를 유발한다는 사실
  - `OTEL-HM-C5`: `http/dup` 모드로 phased rollout이 가능한 공식 opt-in 메커니즘이 존재함
- 이 자료가 증명하지 않는 것:
  - ca-tmpl 혹은 ca-skeleton의 현재 OTel SDK 버전이 어느 semconv 버전을 사용하는지
  - Java OTel agent 의 기본값이 old/stable 중 어떤 것인지 (별도 SDK changelog 확인 필요)
  - 외부 표준 ↔ skeleton registry mapping row 의 column 형식이 무엇이어야 하는지 (D4 UNSUPPORTED_DECISION 영역)
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl 의 실제 OTel instrumentation library 버전 + 해당 버전이 stable semconv를 기본 방출하는지 검증
  - log/metric registry의 mapping row에서 `semconv_version` column을 추가하는 결정(D4 미지원 — 별도 결정 필요)

## 메모 / Notes

- 이 가이드는 non-normative(규범 문서가 아닌 이행 안내)이지만, "are required to implement a migration plan"이라는 표현을 포함해 사실상 의무적 지침으로 작성됨.
- `http.method` → `http.request.method`, `http.status_code` → `http.response.status_code` 등 속성 키도 대규모 rename — metric registry 외 span attribute registry도 mapping row 필요 가능성 있음.
- 추가로 봐야 할 동일 출처 페이지: https://opentelemetry.io/docs/specs/semconv/http/ (stable HTTP semconv 본문)

## Related / 관련

- 같은 주제 다른 official-doc: [[raw/official-docs/metric-otel-metrics-data-model-spec]] (OTel metrics data model)
- 이 자료를 인용한 wiki 요약: (생성 시 추가)