Files
llm-wiki/wiki/concepts/distributed-tracing-baggage.md
T

4.7 KiB

title, source_type, status, confidence, tags, related_projects, last_reviewed
title source_type status confidence tags related_projects last_reviewed
concept / Distributed Tracing & Baggage llm-generated reviewed high
concept
ca-tmpl
observability
mdc
span-event
ca-tmpl
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_idspan_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