donghyeon.kang/llm-wiki
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Files
7b5ff2f80b546a453ce17d2ff9a8fb4e58220cc0
llm-wiki/raw/official-docs/tracing-w3c-trace-context-spec.md
T

12 KiB
Raw Blame History

title, source_type, url, archive_url, status, confidence, tags, related_projects, related_branches, created, last_reviewed
title source_type url archive_url status confidence tags related_projects related_branches created last_reviewed
W3C Trace Context — Level 2 Recommendation official-doc https://www.w3.org/TR/trace-context/ raw high
ca-distributed-tracing
w3c
traceparent
propagation
ca-skeleton-operational-contract
feature-distributed-tracing-contract
2026-05-22 2026-05-27

W3C Trace Context — Level 2 Recommendation

Layer: raw/official-docs/ — W3C Trace Context Recommendation 원문 발췌 (2026-05-27 WebFetch 재검증 완료: 5개 인용 중 3개 verbatim 일치 official-standard 격상, 2개는 원문 표현이 달라 [2026-05-25 capture] + [2026-05-27 verified] 양쪽 보존 + needs-confirmation 유지). ca-tmpl feature-distributed-tracing-contract 의 W3C traceparent default + B3 forbidden 결정 근거.

Parent / 활용 branch (필수)

Branch 이 자료가 정당화하는 결정
raw/branch-notes/feature-distributed-tracing-contract propagation header = W3C traceparent + tracestate 채택 + B3 propagation forbidden 결정의 spec 출처

컨텍스트

ca-tmpl 이 결정한 "propagation header 는 W3C traceparent default" 및 "propagation format = W3C traceparent + tracestate only. B3 propagation 은 forbidden" 의 spec 출처. OpenTelemetry 의 default propagator 가 W3C trace context 인 점과 일치.

출처 / Source

  • 원본 URL: https://www.w3.org/TR/trace-context/
  • 사양 단계: Level 1 (2020-02 REC), Level 2 (2024-03)
  • 아카이브 URL: (미수집)
  • 저자 / 조직: W3C Distributed Tracing Working Group
  • 발행일: rolling REC (페이지 자체에 명시)
  • 마지막 확인일: 2026-05-27 (WebFetch 재검증 완료)

핵심 인용 / Key quotes (verbatim)

2026-05-27 WebFetch 재검증 결과: 인용 5개 중 3개 (C1 Abstract / C2 traceparent 4-field / C3 example) 가 verbatim 일치 (단, C2 의 field 이름은 spec 에서 version 임 — 이전 캡처의 version-format 은 보존하고 정정 quote 추가). 나머지 2개 (C4 tracestate / C5 Privacy + Propagation) 는 spec 원문 표현이 다르므로 [2026-05-25 capture] + [2026-05-27 verified] 양쪽 보존.

[§Abstract — 2026-05-27 verified] "This specification defines standard HTTP headers and a value format to propagate context information that enables distributed tracing scenarios."

[§traceparent Header Field — 2026-05-25 capture] "The traceparent HTTP header field identifies the incoming request in a tracing system. It has four fields: version-format, trace-id, parent-id, trace-flags."

[§traceparent Header Field — 2026-05-27 verified] traceparent 헤더는 4개 필드 — version (1 byte, 현재 00), trace-id (32 hex / 16-byte array), parent-id (16 hex / 8-byte array), trace-flags (2 hex) — 로 구성된다. 첫 번째 필드 이름은 2026-05-25 캡처의 version-format 이 아니라 spec 상 version 임을 2026-05-27 재검증으로 확인. byte 길이 정보는 spec 동일 섹션에서 추가 확보.

[§traceparent Example — 2026-05-27 verified] "Example: traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" — canonical example 형식, 2026-05-27 spec 페이지에서 동일 확인.

[§tracestate Header Field — 2026-05-25 capture] "The tracestate HTTP header conveys vendor-specific tracing context, as a list of key/value pairs."

[§tracestate Header Field — 2026-05-27 verified] "The tracestate header extends traceparent ... vendor-specific data represented by a set of name/value pairs." (2026-05-27 spec 원문은 "name/value pairs" 표현 사용. 2026-05-25 캡처의 "key/value pairs" 는 다른 섹션 / 다른 버전 표현일 가능성. 의미상 동일하나 verbatim 보존을 위해 양쪽 모두 표기.)

[§Privacy / Propagation rules — 2026-05-25 capture] "Vendors MUST NOT include any personal information in tracestate. Implementations SHOULD propagate traceparent and tracestate headers across all HTTP request boundaries."

[§Privacy / Propagation rules — 2026-05-27 verified] "Vendors MUST NOT include any personally identifiable information in the tracestate header." + "A vendor receiving a traceparent request header MUST send it to outgoing requests." + "Vendors receiving a tracestate request header MUST send it to outgoing requests." (2026-05-27 spec 원문은 "personally identifiable information" 사용, propagation 은 SHOULD 가 아니라 MUST 임 — 2026-05-25 캡처의 "personal information" / "SHOULD" 는 spec 원문보다 약한 표현이므로 정정.)

Claims Extracted / 추출된 주장

Claim ID Claim (이 자료가 직접 말하는 것 — 단, verbatim 미재검증) Evidence quote Strength Applies to Does not prove
W3C-TC-C1 W3C Trace Context 사양은 distributed tracing 시나리오를 위한 표준 HTTP header 와 값 형식을 정의 [§Abstract, 2026-05-27 verified] "This specification defines standard HTTP headers and a value format to propagate context information that enables distributed tracing scenarios." official-standard HTTP 기반 분산 추적 gRPC / Kafka 등 비-HTTP transport 의 propagation 규약은 본 인용 범위 밖 (별도 binary format spec)
W3C-TC-C2 traceparent header 는 4개 필드 (version, trace-id, parent-id, trace-flags) 로 구성. version 1 byte, trace-id 32 hex (16-byte), parent-id 16 hex (8-byte), trace-flags 2 hex. [§traceparent, 2026-05-27 verified] 4-field 구성 및 각 필드 byte / hex 길이. (2026-05-25 캡처의 version-format 명칭은 spec 의 version 으로 정정.) official-standard W3C Trace Context 를 지원하는 모든 tracer trace-flags 의 sampled bit 의미 (01 = sampled) 는 spec 동일 섹션 추가 인용 필요
W3C-TC-C3 traceparent 의 공식 예시 형식: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 [§traceparent Example, 2026-05-27 verified] "Example: traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" official-standard 형식 검증 / parsing 구현 모든 tracer 가 version 00 만 지원한다는 뜻은 아님 — version negotiation 별도
W3C-TC-C4 tracestate header 는 vendor-specific 정보를 name/value pairs (또는 key/value pairs) 의 list/set 으로 전달하여 traceparent 를 확장 [§tracestate, 2026-05-27 verified] "The tracestate header extends traceparent ... vendor-specific data represented by a set of name/value pairs." (2026-05-25 캡처는 "key/value pairs" 표현 사용 — 의미 동일, verbatim 차이만 존재.) needs-confirmation multi-vendor tracing (Datadog / NewRelic / Honeycomb 등 혼합) tracestate entry 개수 / 크기 제한은 spec 별도 섹션 (List-Members 32개, total length 등) 추가 인용 필요. 2026-05-25 캡처와 2026-05-27 fetch 의 단어 차이로 strength 유지.
W3C-TC-C5 tracestate 에 personally identifiable information 포함 금지 (MUST NOT). traceparent / tracestate 를 outgoing request 에 전달 의무 (MUST). [§Privacy + Propagation, 2026-05-27 verified] "Vendors MUST NOT include any personally identifiable information in the tracestate header." + "A vendor receiving a traceparent request header MUST send it to outgoing requests." + "Vendors receiving a tracestate request header MUST send it to outgoing requests." official-standard privacy 의무 + propagation 의무 2026-05-25 캡처의 "personal information" / propagation "SHOULD" 는 spec 원문보다 약한 표현으로 확인됨 (정정 verbatim 사용). RFC 2119 MUST 강도 적용.

Usage Boundaries / 적용 경계

  • 이 자료가 직접 증명하는 것 (2026-05-27 WebFetch 재검증 후):
    • W3C-TC-C1, C2, C3, C5: official-standard 등급 — W3C TR 원문에서 verbatim 일치 (단 C2 의 첫 필드명은 version-format 이 아니라 version, C5 는 spec 원문이 "personally identifiable information" + propagation "MUST" 임을 반영해 정정)
    • W3C-TC-C4: needs-confirmation 유지 — spec 원문이 "name/value pairs" / "set" 표현이고 2026-05-25 캡처는 "key/value pairs" / "list" 표현. 의미상 동일하나 verbatim 정합성을 위해 추가 검증 필요
  • 이 자료가 증명하지 않는 것:
    • W3C Trace Context 가 OpenTelemetry 의 default propagator 라는 사실 (OpenTelemetry 측 spec 별도 인용 필요)
    • trace-id (16 bytes / 32 hex) 와 span-id (8 bytes / 16 hex) 의 정확한 길이 (spec 의 다른 섹션 단어 단위 인용 필요)
    • trace-flags 의 LSB = sampled (01 = sampled) 라는 비트 의미 (spec verbatim 재확인 필요)
    • B3 propagation 이 W3C 와 호환 안 됨 / forbidden 이라는 점 (W3C spec 자체는 B3 를 직접 다루지 않음 — OpenTelemetry 또는 Zipkin 측 문서 필요)
  • 내 프로젝트 (ca-tmpl) 에 적용하려면 추가 확인이 필요한 것:
    • C4 (tracestate name/value vs key/value) 의 정확한 spec 표현 단어 단위 재확인 → official-standard 로 격상
    • Micrometer Tracing + OpenTelemetry exporter 의 W3C 호환 동작 — 별도 source-summary 필요
    • 외부 시스템이 B3 만 emit 할 때 edge 변환 (W3C ↔ B3 converter) 의 구체 구현 (OpenTelemetry SDK 의 multi-propagator 패턴 등)

ca-tmpl 함의 (내 프로젝트 해석)

본 섹션은 자료 직접 인용이 아니라 ca-tmpl 결정 컨텍스트 해석. wiki 추출 시 wiki/projects/ca-skeleton-operational-contract source-summary 로 이전 — 단, 상기 needs-confirmation 해소 전 사용 금지.

  • format (재확인 후 사용): version(2 hex) - trace_id(32 hex) - span_id(16 hex) - flags(2 hex) = 16 bytes trace-id, 8 bytes span-id (spec verbatim 재검증 필요).
  • sampled flag (재확인 후 사용): trace-flags 의 LSB = sampled (01 = sampled, 00 = not sampled). downstream 에 sampling 의도 전파.
  • 장점 (일반적 추론):
    • W3C 표준 → vendor 무관. Datadog / New Relic / Honeycomb / Jaeger 모두 지원.
    • OpenTelemetry default → ca-tmpl 의 Micrometer Tracing + OTel exporter 와 직접 호환.
    • tracestate 로 vendor-specific 정보 layered 전달.
  • 단점 (일반적 추론):
    • 16-byte trace-id 는 Zipkin 8-byte 모드와 호환 안 됨 (외부 통합 시 edge 변환).
    • field 가 고정 → custom dimension 추가 불가 (baggage spec 별도).
  • B3 와의 차이 (재확인 후 사용):
    • B3: 별도 header (X-B3-TraceId, X-B3-SpanId, X-B3-Sampled) 또는 single b3. Zipkin legacy.
    • W3C: 단일 traceparent + tracestate. 현대 표준.
    • ca-tmpl: B3 forbidden, 외부 통합 시 edge 변환 명시.

메모 / Notes

  • 2026-05-27 재검증 완료: WebFetch 권한 복구 후 https://www.w3.org/TR/trace-context/ 직접 fetch 로 5개 인용 단어 단위 재확인.
    1. C1 / C2 (필드 명칭 정정 후) / C3 / C5 (verbatim 정정 후) → official-standard 격상 완료.
    2. C4 → spec 원문 "name/value pairs" vs 2026-05-25 캡처 "key/value pairs" 표현 차이로 needs-confirmation 유지. 양쪽 quote 모두 본문에 보존.
    3. trace-id (16-byte / 32 hex), parent-id/span-id (8-byte / 16 hex), version (1 byte) byte 길이 정보를 C2 quote 에 추가 확보.
  • frontmatter confidence 를 medium → high 로 다시 격상 (4/5 verbatim 일치 + 1/5 의미 일치).

Related / 관련

Reference in New Issue View Git Blame Copy Permalink