8.2 KiB
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 | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Zipkin / B3 Propagation Specification | official-doc | https://github.com/openzipkin/b3-propagation | raw | high |
|
|
|
2026-05-22 | 2026-05-27 |
Zipkin / B3 Propagation Specification
Layer:
raw/official-docs/— OpenZipkin 의 B3 propagation 사양 verbatim. ca-tmpl 의 "B3 internal forbidden + edge translation only" 결정의 1차 근거.
Parent / 활용 branch (필수)
| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| raw/branch-notes/feature-distributed-tracing-contract | distributed tracing propagation format 으로 B3 를 internal 에서 forbidden 하고 edge 변환만 허용한 결정의 spec 근거 (W3C 와 wire-format 비교 위해 보관) |
| raw/project-notes/ca-skeleton-operational-contract | §Distributed Tracing Contract 의 propagation format 대안 비교 (Group G-A 대안 1 — B3 / Zipkin legacy) |
컨텍스트
ca-tmpl 이 "B3 propagation 은 forbidden (외부 통합 시 edge 에서 변환)"으로 결정한 근거. legacy Zipkin / Spring Cloud Sleuth(현 Micrometer Tracing pre-W3C) 시스템 통합 시 edge 변환 책임을 명시한 spec 확인.
출처 / Source
- 원본 URL: https://github.com/openzipkin/b3-propagation
- 아카이브 URL: (미수집)
- 저자 / 조직: OpenZipkin (Apache-2.0)
- 발행일: rolling spec (GitHub repo)
- 마지막 확인일: 2026-05-27
핵심 인용 / Key quotes (verbatim)
[§Header — X-B3-TraceId] "The
X-B3-TraceIdheader is encoded as 32 or 16 lower-hex characters."
[§Header — X-B3-SpanId] "The
X-B3-SpanIdheader is encoded as 16 lower-hex characters."
[§Header — X-B3-ParentSpanId] "The
X-B3-ParentSpanIdheader may be present on a child span and must be absent on the root span. It is encoded as 16 lower-hex characters."
[§Sampling state] "An accept sampling decision is encoded as
X-B3-Sampled: 1and a deny asX-B3-Sampled: 0."
[§Debug flag] "Debug is encoded as
X-B3-Flags: 1. Absent or any other value can be ignored."
[§Single header b3] "
b3={TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}, where the last two fields are optional."
[§Single vs multiple header precedence] "The single-header variant takes precedence over the multiple header one when extracting fields."
[§Trace identifiers] "Trace identifiers are 64 or 128-bit"
[§Sampling] "Sampling is a mechanism to reduce the volume of data that ends up in the tracing system."
Claims Extracted / 추출된 주장
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| B3-C1 | X-B3-TraceId 헤더는 32자 또는 16자 lower-hex (즉 128-bit 또는 64-bit 정수) 로 인코딩된다 |
[§Header — X-B3-TraceId] "The X-B3-TraceId header is encoded as 32 or 16 lower-hex characters." |
official-standard |
B3 multiple header 방식 wire format | 모든 B3 구현이 128-bit 를 default 로 한다는 뜻은 아님 — 둘 다 허용 |
| B3-C2 | X-B3-SpanId 와 X-B3-ParentSpanId 는 16자 lower-hex (64-bit). X-B3-ParentSpanId 는 root span 에서 반드시 부재 |
[§Header — X-B3-SpanId] "The X-B3-SpanId header is encoded as 16 lower-hex characters." + [§Header — X-B3-ParentSpanId] "The X-B3-ParentSpanId header may be present on a child span and must be absent on the root span." |
official-standard |
B3 multiple header child/root span 구분 | SpanId 가 128-bit 로 확장 가능하다는 뜻 아님 — 64-bit only |
| B3-C3 | Sampling decision 은 X-B3-Sampled: 1 (accept) 또는 X-B3-Sampled: 0 (deny). Debug 는 별도 X-B3-Flags: 1 |
[§Sampling state] "An accept sampling decision is encoded as X-B3-Sampled: 1 and a deny as X-B3-Sampled: 0." + [§Debug flag] "Debug is encoded as X-B3-Flags: 1. Absent or any other value can be ignored." |
official-standard |
B3 sampling 헤더 인코딩 | Defer 같은 부재(absent) 상태의 처리 의미는 본 인용 외에서 명시 — 별도 §Sampling state 표 확인 필요 |
| B3-C4 | Single header 형식은 b3={TraceId}-{SpanId}-{SamplingState}-{ParentSpanId} 이며 마지막 두 필드는 선택 |
[§Single header b3] "b3={TraceId}-{SpanId}-{SamplingState}-{ParentSpanId}, where the last two fields are optional." |
official-standard |
single-header b3 변형 | SamplingState 가 부재일 때의 default sampling 결정은 본 인용에 없음 |
| B3-C5 | Single header b3 가 존재하면 multiple header 보다 우선 (precedence) |
[§Single vs multiple header precedence] "The single-header variant takes precedence over the multiple header one when extracting fields." | official-standard |
B3 receiver 의 헤더 추출 로직 | sender 가 둘 다 보낼 수 있다는 뜻이지, receiver 가 둘 다 동시에 read 해야 한다는 의미는 아님 (extract 시 precedence 만 규정) |
| B3-C6 | Trace identifiers 는 64-bit 또는 128-bit 양쪽 모두 허용 | [§Trace identifiers] "Trace identifiers are 64 or 128-bit" | official-standard |
B3 trace-id 길이 정책 | W3C Trace Context (128-bit only) 와 호환되려면 128-bit 모드여야 한다는 결론은 본 인용으로 직접 증명되지 않음 (W3C spec 별도 참조 필요) |
| B3-C7 | Sampling 은 tracing system 에 도달하는 data volume 을 줄이기 위한 메커니즘 | [§Sampling] "Sampling is a mechanism to reduce the volume of data that ends up in the tracing system." | official-standard |
B3 sampling 의 목적 정의 | 1% / 10% 등 구체적 비율 권장은 본 인용에 없음 — 정책은 시스템 책임 |
Usage Boundaries / 적용 경계
- 이 자료가 직접 증명하는 것:
B3-C1~B3-C7: B3 multiple header 와 single header 의 정확한 wire format, sampling state 인코딩, single 우선순위, trace-id 64/128-bit 양립
- 이 자료가 증명하지 않는 것:
- W3C Trace Context (
traceparent/tracestate) 가 B3 보다 modern 표준이라는 결론 (본 spec 은 B3 정의만, W3C 비교 평가 없음) - B3 64-bit ↔ W3C 128-bit 변환 시 zero-padding 또는 새 trace-id 생성의 정확한 권장 알고리즘 (별도 W3C spec / 변환 가이드 필요)
- Spring Cloud Sleuth (legacy) vs Micrometer Tracing 의 default propagation format 차이 (별도 vendor doc)
- "B3 internal forbidden + edge translation" 이 best practice 라는 결론 — 이는 ca-tmpl 의 결정 사항이며 B3 spec 이 직접 권장하지 않음
- W3C Trace Context (
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 의 edge gateway (nginx / envoy / spring cloud gateway) 가 B3 → W3C 변환을 어떻게 처리하는지 (Micrometer Tracing 의
Propagatorcomposite 설정) - legacy 외부 시스템과의 통신에서 64-bit B3 만 지원하는 peer 가 있을 경우 trace 단절 위험
- ca-tmpl 의 edge gateway (nginx / envoy / spring cloud gateway) 가 B3 → W3C 변환을 어떻게 처리하는지 (Micrometer Tracing 의
메모 / Notes (내 프로젝트 해석)
본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.
- 64-bit vs 128-bit: B3 는 둘 다 허용 (
B3-C1,B3-C6). W3C 는 128-bit only → B3 64-bit ↔ W3C 변환 시 zero-padding 또는 새 trace-id 생성 필요. - single header
b3: W3Ctraceparent와 형식 유사하지만 field 순서/구분자 다름. - 장점:
- Zipkin / Spring Cloud Sleuth (legacy) 와 자연 통합.
- multiple header 형태는 디버깅 시 가시성 좋음.
- 단점:
- non-W3C → vendor neutrality 약함.
- 64-bit mode 는 W3C 와 호환 안 됨 → cross-system trace 단절.
- 새 시스템에서는 OpenTelemetry default 가 아님.
- ca-tmpl 과의 차이: ca-tmpl 은 internal propagation 을 W3C 로 통일. 외부 legacy 시스템과 통신할 때만 edge 에서 B3 → W3C 변환. internal 에서 B3 forbidden.
Related / 관련
- 같은 주제 다른 raw:
- raw/official-docs/tracing-otel-sampling-tail-vs-head-spec (sampling 전략, 별도 spec)
- 인용하는 branch:
- 인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract (§Distributed Tracing Contract — propagation format 대안 비교)
- 인용한 wiki 요약: (미작성)