init: llm-wiki-haness 하네스 설계

vault/30-knowledge/concepts/distributed-tracing-baggage.md

@@ -0,0 +1,64 @@
+---
+title: concept / Distributed Tracing & Baggage
+source_type: llm-generated
+status: reviewed
+confidence: high
+tags: [concept, ca-tmpl, observability, mdc, span-event]
+related_projects: [ca-tmpl]
+last_reviewed: 2026-06-15
+---
+
+# concept / Distributed Tracing & Baggage
+
+## Summary
+
+여러 마이크로서비스를 거쳐 흐르는 단일 요청의 실행 흐름을 시각화하고 진단할 수 있도록 트레이스 ID와 스팬 ID 등의 메타데이터(TraceContext)를 전파하고, 전체 트레이스 수명 주기 동안 요청 전반에 걸쳐 데이터를 전달(Baggage)하는 기술.
+
+## Standard (공식 정의)
+
+W3C Distributed Tracing 및 OpenTelemetry 표준 명세에 따른 정의는 다음과 같다.
+- **traceparent**: 실행 중인 분산 요청의 컨텍스트를 규격화한 W3C 공식 헤더.
+  - 형식: `version-traceId-parentId-traceFlags` (예: `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01`)
+  - `traceFlags`의 마지막 비트가 `01`이면 샘플링됨(Sampled), `00`이면 샘플링되지 않음(Not-Sampled)을 나타낸다.
+- **baggage**: 분산 트레이스 경계 전반에 걸쳐 임의의 키-값 쌍 메타데이터를 전파하기 위한 W3C 헤더 규격. 클라이언트 요청 처리 중 하위 모든 마이크로서비스 호출 시에 함께 흘러간다.
+  - 형식: `key1=value1,key2=value2`
+
+## 한계 / 주의점
+
+- **보안 경계 허점 (Security Boundary Risk)**: Baggage는 하위 시스템과 외부 네트워크 경계까지 쉽게 유실/전파될 수 있으므로, 민감 정보(자격증명, 개인정보(PII), 비밀 토큰)가 포함될 경우 데이터 유출의 주요 통로가 된다. 따라서 반드시 어댑터 송출 단계에서 엄격한 허용 목록(Allowlist) 필터링을 거치거나 원천 차단해야 한다.
+- **샘플링 불일치 (Sampling Mismatch)**: 마이크로서비스 상위 계층에서 샘플링되지 않은(`00`) 트레이스 헤더가 다운스트림으로 내려가면 하위 서비스들은 해당 요청에 대한 상세 스팬 지표를 수집하지 않고 드랍할 수 있어, 트레이스 경로가 끊어지는 현상이 발생할 수 있다.
+
+## Project Application
+
+- [[wiki/explainer/adapter-outbound.md]]
+- `TraceContextPropagationInterceptor`가 RestClient 요청 송출 시 MDC(Mapped Diagnostic Context)에 저장된 트레이스 및 배기지 컨텍스트를 가로채 전파함.
+  - `traceparent`는 MDC `trace_id`와 `span_id`를 기반으로 동적으로 조립되어 전송됨 (현재는 추적 서버로 전송하지 않는 기본 뼈대이므로 샘플 플래그는 `00`으로 고정함).
+  - `baggage`의 경우 보안 누출 방지를 위해 오직 **`request_id`**와 **`tenant_id`** 두 가지만 통과시키는 허용 목록 필터링(`BaggageAllowlist.filter`)을 적용함.
+
+## Claim-backed Knowledge
+
+| Knowledge Point | Supporting Claims | Confidence | Notes |
+|---|---|---|---|
+| W3C traceparent 헤더 포맷 및 전파 규격 | `raw/official-docs/trace-context-w3c-recommendation.md` | `high` | W3C 공식 권고안 |
+| Baggage API 스펙 및 데이터 필터링 필요성 | `raw/official-docs/baggage-w3c-baggage-spec.md` | `high` | W3C Baggage 사양 |
+
+## 내가 설명할 수 있어야 하는 것
+
+- `traceparent` 헤더의 구성 요소와 샘플링 플래그(`01`/`00`)의 역할은 무엇인가?
+- 왜 Baggage 전파 시 Allowlist 기반의 보안 필터링이 필수적으로 수반되어야 하는가?
+- 우리 아웃바운드 HTTP 클라이언트의 트레이싱 전파 시 뼈대 코드(Skeleton)의 한계는 무엇이며, 향후 실무 OTel SDK 연동 시 어떻게 대응해야 하는가? (하드코딩된 `00` 샘플링 해제 및 OTel RestClient Interceptor로의 전환)
+
+## Interview Questions
+
+- 마이크로서비스 간 분산 트레이싱을 구현할 때 HTTP 헤더 전파(Propagation) 과정과 Baggage 활용 시 주의해야 할 보안 위협에 대해 설명해 주세요.
+- MDC 기반 트레이싱 컨텍스트와 실제 OpenTelemetry / Micrometer Tracing API의 생명 주기를 멀티스레드 환경에서 어떻게 안전하게 바인딩할 수 있습니까?
+
+## Do Not Overclaim
+
+- "MDC 정보가 자동으로 헤더로 전파되므로 어떤 환경에서든 분산 트레이싱이 정상 작동한다"고 과장해서는 안 된다. 멀티스레드 비동기 작업(TaskExecutor 사용 시)이나 리액티브 환경에서는 MDC가 유실되므로 별도의 Context Propagator를 직접 정의하여 스레드 경계를 가로지르는 전파 설계를 갖춰야만 보장된다.
+
+## Sources
+
+- [W3C Recommendation for Trace Context](https://www.w3c.org/TR/trace-context/)
+- [[raw/official-docs/trace-context-w3c-recommendation.md]]
+- [[raw/official-docs/baggage-w3c-baggage-spec.md]]