---
title: Zipkin / B3 Propagation Specification
source_type: official-doc
url: https://github.com/openzipkin/b3-propagation
archive_url:
status: raw
confidence: high
tags: [ca-distributed-tracing, b3, zipkin, propagation, legacy, official-doc]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-distributed-tracing-contract]
created: 2026-05-22
last_reviewed: 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-TraceId` header is encoded as 32 or 16 lower-hex characters."

> [§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. It is encoded as 16 lower-hex characters."

> [§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."

> [§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 이 직접 권장하지 않음
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 의 edge gateway (nginx / envoy / spring cloud gateway) 가 B3 → W3C 변환을 어떻게 처리하는지 (Micrometer Tracing 의 `Propagator` composite 설정)
  - legacy 외부 시스템과의 통신에서 64-bit B3 만 지원하는 peer 가 있을 경우 trace 단절 위험

## 메모 / 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`:** W3C `traceparent` 와 형식 유사하지만 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:
  - [[raw/branch-notes/feature-distributed-tracing-contract]]
- 인용하는 project:
  - [[raw/project-notes/ca-skeleton-operational-contract]] (§Distributed Tracing Contract — propagation format 대안 비교)
- 인용한 wiki 요약: (미작성)