{"id":2169,"library":"opentelemetry-propagator-b3","title":"OpenTelemetry B3 Propagator","description":"The `opentelemetry-propagator-b3` library provides B3 context propagation for OpenTelemetry Python, enabling distributed tracing across systems that use the B3 header format (e.g., Zipkin). It is part of the broader OpenTelemetry Python project, which follows a rapid release cycle, with new versions typically released monthly.","status":"active","version":"1.41.0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python","tags":["opentelemetry","observability","tracing","propagation","b3","zipkin"],"install":[{"cmd":"pip install opentelemetry-propagator-b3 opentelemetry-sdk","lang":"bash","label":"Install library and SDK"}],"dependencies":[{"reason":"Core OpenTelemetry API for defining and interacting with telemetry concerns.","package":"opentelemetry-api","optional":false},{"reason":"OpenTelemetry SDK provides the reference implementation for the API, required for actual telemetry processing and export.","package":"opentelemetry-sdk","optional":false}],"imports":[{"symbol":"B3Propagator","correct":"from opentelemetry.propagators.b3 import B3Propagator"},{"note":"`set_global_textmap` is located in `opentelemetry.propagate`, not directly under `opentelemetry.propagators`.","wrong":"from opentelemetry.propagators import set_global_textmap","symbol":"set_global_textmap","correct":"from opentelemetry.propagate import set_global_textmap"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.propagate import set_global_textmap, get_global_textmap\nfrom opentelemetry.propagators.b3 import B3Propagator\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\n\n# Set the B3 propagator globally\nset_global_textmap(B3Propagator())\n\n# Configure a basic tracer provider for demonstration\nprovider = TracerProvider()\nprocessor = SimpleSpanProcessor(ConsoleSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\ntracer = trace.get_tracer(__name__)\n\ndef make_request():\n    carrier = {}\n    propagator = get_global_textmap()\n    # Inject context into a carrier (e.g., HTTP headers)\n    propagator.inject(carrier=carrier)\n    print(f\"Injected B3 headers: {carrier}\")\n\n    # Simulate receiving context in another service\n    # Here, we just extract from the same carrier for simplicity\n    ctx = propagator.extract(carrier=carrier)\n\n    with tracer.start_as_current_span(\"my-b3-propagated-span\", context=ctx):\n        print(\"Span created with propagated B3 context\")\n\nif __name__ == \"__main__\":\n    make_request()\n","lang":"python","description":"This quickstart demonstrates how to set the B3 propagator globally and use it to inject trace context into a carrier (like HTTP headers) and then extract it. This is crucial for distributed tracing where context needs to be passed between services. The `opentelemetry-sdk` is used here for a runnable example, but in a real application, you would configure exporters and resource detectors appropriately."},"warnings":[{"fix":"For multi-header injection, you might need to use `B3MultiFormat` directly or configure `B3Propagator` if a future version exposes an `injectEncoding` option (check latest documentation). Alternatively, use environment variables `OTEL_PROPAGATORS=\"b3multi\"`.","message":"By default, the `B3Propagator` extracts both single (`b3`) and multi-header (`X-B3-*`) B3 formats but injects only the single-header `b3` format. If your system requires multi-header injection for compatibility with legacy systems, explicit configuration is needed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of this difference when integrating with existing Zipkin systems that might rely on `X-B3-ParentSpanId`. The OpenTelemetry span model creates distinct client and server spans.","message":"The OpenTelemetry B3 propagator intentionally does not propagate `X-B3-ParentSpanId`. This is because OpenTelemetry does not support the Zipkin-specific behavior of reusing the same ID for both client and server sides of a request, which `ParentSpanId` implies.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Call `set_global_textmap(B3Propagator())` during your application's startup, or set the environment variable `OTEL_PROPAGATORS=\"b3\"` (for single header injection) or `OTEL_PROPAGATORS=\"b3multi\"` (if using a mechanism that allows it, usually implies `CompositePropagator` in code with `B3MultiFormat`).","message":"The OpenTelemetry Python SDK defaults to using W3C Trace Context and W3C Baggage propagators. To enable B3 propagation, you must explicitly set `B3Propagator` as the global text map propagator in your application's initialization code, or use environment variables.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}