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

title, source_type, url, archive_url, related_branches, related_projects, tags, created

title	source_type	url	archive_url	related_branches	related_projects	tags	created
HTTP Semantic Convention Stability Migration — OpenTelemetry Official Guide	official-doc	https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/		feature-contract-registry-governance	ca-skeleton	official-doc ca-skeleton observability opentelemetry metric-naming	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 요약: (생성 시 추가)