7.3 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 Baggage API Specification (Stable) | official-doc | https://opentelemetry.io/docs/specs/otel/baggage/api/ |
|
|
|
2026-06-14 |
OpenTelemetry Baggage API Specification (Stable)
Layer:
raw/— 외부 자료(공식 문서)의 원문 발췌·출처 기록. 검증된 요약은/ingest후wiki/concepts/에source-summary-template형식으로 별도 작성. 원본은 raw에 영구 보관.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-distributed-tracing-contract | D2: baggage 에 PII/token 금지의 SDK 수준 escape hatch (untrusted process 로의 전송 방지 MUST 요건); D8: allowlist 는 spec 정의 없음 — propagator/application 위임 확인 (스펙에 allowlist 정의 부재, restriction 은 Propagator 가 독자 부과) |
출처 / Source
- 원본 URL: https://opentelemetry.io/docs/specs/otel/baggage/api/
- 아카이브 URL: (미등록)
- 저자 / 조직: OpenTelemetry Authors (CNCF)
- 발행일: (Stable 사양 — 정확한 날짜 미확인)
- 마지막 확인일: 2026-06-14
왜 저장했는지 / Why archived
feature-distributed-tracing-contract 브랜치의 D2(baggage PII 금지)와 D8(allowlist 는 정책이지 스펙이 아님) 결정의 직접 근거가 되는 OTel 공식 사양. W3C trace context 스펙은 tracestate PII 금지를 다루지만 baggage 자체의 보안 요건은 이 문서에서만 확인 가능. D8의 핵심 — spec 은 allowlist 를 정의하지 않고 Propagator 에게 restriction 위임 — 도 이 문서에서 직접 확인.
핵심 인용 / Key quotes (verbatim, 3~5문장)
[§Overview / Definition] "Baggage is a set of application-defined properties contextually associated with a distributed request or workflow execution"
[§Data Model] "In OpenTelemetry Baggage is represented as a set of name/value pairs describing user-defined properties. Each name in Baggage MUST be associated with exactly one value."
[§Security Considerations / Clear Baggage] "To avoid sending any name/value pairs to an untrusted process, the Baggage API MUST provide a way to remove all baggage entries from a context."
[§Baggage Names / Propagator Restrictions] "the specific Propagators that are used to transmit baggage entries across component boundaries may impose their own restrictions on baggage names."
[§Baggage Container / Immutability] "The Baggage container MUST be immutable, so that the containing Context also remains immutable."
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| OTEL-BAG-C1 | OTel Baggage 는 분산 요청/워크플로우 실행에 연관된 application-defined properties 집합이다 | [§Overview] "Baggage is a set of application-defined properties contextually associated with a distributed request or workflow execution" | official-vendor-doc |
OTel SDK 를 사용하는 모든 언어 구현 | Baggage 가 특정 HTTP header 형식으로 전송된다는 것은 증명하지 않음 (Propagator 에 위임) |
| OTEL-BAG-C2 | Baggage 의 데이터 모델은 name/value 쌍의 집합이며 각 name 은 정확히 하나의 value 와 연관되어야 한다 | [§Data Model] "In OpenTelemetry Baggage is represented as a set of name/value pairs describing user-defined properties. Each name in Baggage MUST be associated with exactly one value." | official-vendor-doc |
OTel Baggage API 구현 전체 | Baggage name/value 의 허용 문자 범위나 크기 제한을 직접 확정하지 않음 (Propagator 가 추가 제한 가능) |
| OTEL-BAG-C3 | Baggage API 는 untrusted process 로의 전송을 막기 위해 context 에서 모든 baggage entry 를 제거하는 방법을 MUST 로 제공해야 한다 | [§Security] "To avoid sending any name/value pairs to an untrusted process, the Baggage API MUST provide a way to remove all baggage entries from a context." | official-vendor-doc |
신뢰 경계(trust boundary)를 넘는 모든 OTel Baggage 사용 사례 | 어떤 정보가 "untrusted" 인지(예: PII, token)를 spec 이 직접 정의하지 않음 — application/governance 정책이 결정 |
| OTEL-BAG-C4 | spec 은 baggage name 에 대한 allowlist 를 정의하지 않는다 — 각 Propagator 가 독자적인 restriction 을 부과할 수 있다 | [§Baggage Names] "the specific Propagators that are used to transmit baggage entries across component boundaries may impose their own restrictions on baggage names." | official-vendor-doc |
baggage allowlist 또는 key 제한 정책을 설계할 때 | Propagator 가 실제로 어떤 restriction 을 부과하는지, 또는 반드시 부과해야 하는지를 증명하지 않음 |
| OTEL-BAG-C5 | Baggage container 는 immutable 이어야 하며 이는 포함하는 Context 도 immutable 하게 유지함을 의미한다 | [§Operations] "The Baggage container MUST be immutable, so that the containing Context also remains immutable." | official-vendor-doc |
OTel Context propagation 전반 | Immutability 의 구체적인 구현 방식(copy-on-write vs rebuild 등)을 spec 이 지시하지 않음 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
OTEL-BAG-C3: Baggage API 에는 모든 entry 를 일괄 제거하는 기능이 SDK 수준 MUST 요건으로 존재 → D2 의 "SDK-level escape hatch" 근거OTEL-BAG-C4: OTel spec 은 baggage name allowlist 를 정의하지 않음. restriction 은 Propagator 또는 application 이 독자 부과 → D8 의 "allowlist 는 정책이지 스펙이 아님" 근거OTEL-BAG-C2: name 과 value 의 데이터 모델 기본 계약 (1:1 매핑, RFC 2119 MUST)
- 이 자료가 증명하지 않는 것:
- 어떤 구체적인 key (예:
tenant_id,request_id) 가 baggage 에 적합한지는 spec 범위 밖 — application governance 결정 - PII 나 token 이 구체적으로 어떤 형태인지를 spec 이 정의하지 않음 (
OTEL-BAG-C3Does not prove) - W3C Baggage HTTP header 스펙과의 relationship — 별도 W3C 문서 필요
- 어떤 구체적인 key (예:
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 이 실제로 OTel SDK 의 "clear all baggage" API 를 trust boundary 에서 호출하는지 구현 검증 필요
- W3C Baggage Propagator 가
tenant_id/request_idkey 에 추가 restriction 을 부과하는지 확인 필요
메모 / Notes
- OTEL-BAG-C3 의 "untrusted process" 기준은 application 이 정의해야 함. ca-tmpl 의 D2 결정(PII/token 금지)은 이 MUST 요건을 구체화한 내부 정책.
- OTEL-BAG-C4 는 D8 의 핵심 증거: spec 이 allowlist 를 정의하지 않으므로
tenant_id/request_id만 허용하는 ca-tmpl 정책은 external standard 가 아닌 governance policy 임을 명확히 한다. - 추가로 봐야 할 동일 출처 페이지: https://opentelemetry.io/docs/specs/otel/baggage/data-model/ (data model 상세)
Related / 관련
- 같은 주제 다른 official-doc: raw/official-docs/tracing-w3c-trace-context-spec (tracestate PII MUST NOT — D2 의 W3C 측 근거)
- 이 자료를 인용한 wiki 요약: (미작성 —
/ingest후wiki/concepts/생성 예정)