Registry /
observability / opentelemetry-processor-baggage
Install & Compatibility
Where this runs
tested against v0.65b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.228s · 22.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.5s · import 0.218s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BaggageSpanProcessor
✓ from opentelemetry.processor.baggage import BaggageSpanProcessor, ALLOW_ALL_BAGGAGE_KEYS
This quickstart demonstrates how to configure the `BaggageSpanProcessor` with a `TracerProvider` to automatically copy baggage entries as span attributes. It shows both copying all baggage entries and using a custom predicate to filter which entries are copied. Baggage is set on the context and then automatically appears as attributes on subsequent spans.
import os
from opentelemetry import baggage, trace
from opentelemetry.context import attach, detach
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleExportSpanProcessor
from opentelemetry.processor.baggage import BaggageSpanProcessor, ALLOW_ALL_BAGGAGE_KEYS
# --- Example 1: Copy all baggage entries to span attributes ---
# Configure TracerProvider
provider = TracerProvider()
# Add the BaggageSpanProcessor to copy all baggage entries to span attributes
provider.add_span_processor(BaggageSpanProcessor(ALLOW_ALL_BAGGAGE_KEYS))
# Add a console exporter for demonstration
provider.add_span_processor(SimpleExportSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)
# Create a context with baggage
# IMPORTANT: Baggage entries are strings, convert non-string values
ctx = baggage.set_baggage("user.id", "user123")
ctx = baggage.set_baggage("tenant.id", "acme", context=ctx)
ctx_token = attach(ctx)
try:
with tracer.start_as_current_span("parent_span") as parent_span:
print(f"Parent Span ID: {parent_span.context.span_id:x}")
# Baggage is automatically propagated to child spans
with tracer.start_as_current_span("child_span") as child_span:
print(f"Child Span ID: {child_span.context.span_id:x}")
print(f"Child Span Attributes (should contain baggage): {child_span.attributes}")
finally:
detach(ctx_token)
print("\n--- Example 2: Copy baggage entries with a custom predicate ---")
# Configure a new provider with a custom predicate
provider_custom = TracerProvider()
# Only copy baggage entries starting with 'my-key'
starts_with_predicate = lambda baggage_key: baggage_key.startswith("my-key")
provider_custom.add_span_processor(BaggageSpanProcessor(starts_with_predicate))
provider_custom.add_span_processor(SimpleExportSpanProcessor(ConsoleSpanExporter()))
trace.set_tracer_provider(provider_custom) # Set this new provider
tracer_custom = trace.get_tracer("custom_predicate_example")
ctx_custom = baggage.set_baggage("my-key-1", "value1")
ctx_custom = baggage.set_baggage("other-key", "value_ignored", context=ctx_custom)
ctx_custom_token = attach(ctx_custom)
try:
with tracer_custom.start_as_current_span("filtered_span") as filtered_span:
print(f"Filtered Span ID: {filtered_span.context.span_id:x}")
print(f"Filtered Span Attributes (should only contain 'my-key-1'): {filtered_span.attributes}")
finally:
detach(ctx_custom_token)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'opentelemetry.processor.baggage'
The `BaggageSpanProcessor` is located in the `opentelemetry-processor-baggage` library, and developers often try to import it from common OpenTelemetry SDK paths like `opentelemetry.sdk.trace.export` instead of its specific location.
fixEnsure the `opentelemetry-processor-baggage` package is installed (`pip install opentelemetry-processor-baggage`) and import it correctly using `from opentelemetry.processor.baggage import BaggageSpanProcessor`.
baggage: {}
This output indicates that baggage values are not being retrieved or displayed as expected, often because the `BaggageSpanProcessor` has not been configured with a predicate (like `ALLOW_ALL_BAGGAGE_KEYS`) to specify which baggage entries should be copied as span attributes.
fixWhen adding the `BaggageSpanProcessor` to your `TracerProvider`, ensure you pass a predicate to its constructor. For example, to copy all baggage entries, use `from opentelemetry.processor.baggage import BaggageSpanProcessor, ALLOW_ALL_BAGGAGE_KEYS; tracer_provider.add_span_processor(BaggageSpanProcessor(ALLOW_ALL_BAGGAGE_KEYS))`.
Baggage add/update in Span Processor is not working
OpenTelemetry's `Context` and `Baggage` objects are immutable. Attempting to modify baggage directly within a `SpanProcessor`'s `on_start` or `on_end` method will not affect the propagated context for subsequent spans because these methods do not return an updated context to be used.
fixBaggage should be set on the context *before* creating the span if you want it to be propagated to child spans. If you need to add specific attributes to the current span based on baggage, read the baggage entries and use `span.set_attribute()` directly on the span being processed. `SpanProcessor` is primarily for reading and transforming spans, not for modifying the propagating baggage itself.
Upgrade
Version history
0.65b0latest on PyPI · released Jul 16, 2026
Audit
Dependencies
PythonrequiredRequired for the library.
opentelemetry-sdkrequiredCore OpenTelemetry SDK components are required for tracer provider configuration.
opentelemetry-apirequiredCore OpenTelemetry API for baggage and tracing.