81 lines
7.3 KiB
Markdown
81 lines
7.3 KiB
Markdown
---
|
|
title: "OpenTelemetry Baggage API Specification (Stable)"
|
|
source_type: official-doc
|
|
url: https://opentelemetry.io/docs/specs/otel/baggage/api/
|
|
archive_url:
|
|
related_branches: [feature-distributed-tracing-contract]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, observability, opentelemetry]
|
|
created: 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-C3` Does not prove)
|
|
- W3C Baggage HTTP header 스펙과의 relationship — 별도 W3C 문서 필요
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- ca-tmpl 이 실제로 OTel SDK 의 "clear all baggage" API 를 trust boundary 에서 호출하는지 구현 검증 필요
|
|
- W3C Baggage Propagator 가 `tenant_id` / `request_id` key 에 추가 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/` 생성 예정)
|