{"id":2652,"library":"opentelemetry-processor-baggage","title":"OpenTelemetry Baggage Span Processor","description":"The `opentelemetry-processor-baggage` library provides a `BaggageSpanProcessor` for OpenTelemetry Python, which automatically reads entries stored in Baggage from the parent context and adds their keys and values to the span as attributes upon span start. This enables propagating business context across services. It is part of the `opentelemetry-python-contrib` repository, which has an active release cadence, often with pre-release (`0.x.y.b0`) versions. The current version is 0.62b0.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","tracing","baggage","span processor","context propagation","observability"],"install":[{"cmd":"pip install opentelemetry-processor-baggage","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for the library.","package":"Python","version":">=3.9","optional":false},{"reason":"Core OpenTelemetry SDK components are required for tracer provider configuration.","package":"opentelemetry-sdk","optional":false},{"reason":"Core OpenTelemetry API for baggage and tracing.","package":"opentelemetry-api","optional":false}],"imports":[{"symbol":"BaggageSpanProcessor","correct":"from opentelemetry.processor.baggage import BaggageSpanProcessor, ALLOW_ALL_BAGGAGE_KEYS"}],"quickstart":{"code":"import os\nfrom opentelemetry import baggage, trace\nfrom opentelemetry.context import attach, detach\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleExportSpanProcessor\nfrom opentelemetry.processor.baggage import BaggageSpanProcessor, ALLOW_ALL_BAGGAGE_KEYS\n\n# --- Example 1: Copy all baggage entries to span attributes ---\n\n# Configure TracerProvider\nprovider = TracerProvider()\n# Add the BaggageSpanProcessor to copy all baggage entries to span attributes\nprovider.add_span_processor(BaggageSpanProcessor(ALLOW_ALL_BAGGAGE_KEYS))\n# Add a console exporter for demonstration\nprovider.add_span_processor(SimpleExportSpanProcessor(ConsoleSpanExporter()))\ntrace.set_tracer_provider(provider)\n\ntracer = trace.get_tracer(__name__)\n\n# Create a context with baggage\n# IMPORTANT: Baggage entries are strings, convert non-string values\nctx = baggage.set_baggage(\"user.id\", \"user123\")\nctx = baggage.set_baggage(\"tenant.id\", \"acme\", context=ctx)\nctx_token = attach(ctx)\n\ntry:\n    with tracer.start_as_current_span(\"parent_span\") as parent_span:\n        print(f\"Parent Span ID: {parent_span.context.span_id:x}\")\n        # Baggage is automatically propagated to child spans\n        with tracer.start_as_current_span(\"child_span\") as child_span:\n            print(f\"Child Span ID: {child_span.context.span_id:x}\")\n            print(f\"Child Span Attributes (should contain baggage): {child_span.attributes}\")\nfinally:\n    detach(ctx_token)\n\nprint(\"\\n--- Example 2: Copy baggage entries with a custom predicate ---\")\n\n# Configure a new provider with a custom predicate\nprovider_custom = TracerProvider()\n# Only copy baggage entries starting with 'my-key'\nstarts_with_predicate = lambda baggage_key: baggage_key.startswith(\"my-key\")\nprovider_custom.add_span_processor(BaggageSpanProcessor(starts_with_predicate))\nprovider_custom.add_span_processor(SimpleExportSpanProcessor(ConsoleSpanExporter()))\ntrace.set_tracer_provider(provider_custom) # Set this new provider\n\ntracer_custom = trace.get_tracer(\"custom_predicate_example\")\n\nctx_custom = baggage.set_baggage(\"my-key-1\", \"value1\")\nctx_custom = baggage.set_baggage(\"other-key\", \"value_ignored\", context=ctx_custom)\nctx_custom_token = attach(ctx_custom)\n\ntry:\n    with tracer_custom.start_as_current_span(\"filtered_span\") as filtered_span:\n        print(f\"Filtered Span ID: {filtered_span.context.span_id:x}\")\n        print(f\"Filtered Span Attributes (should only contain 'my-key-1'): {filtered_span.attributes}\")\nfinally:\n    detach(ctx_custom_token)\n","lang":"python","description":"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."},"warnings":[{"fix":"Only use Baggage for non-sensitive identifiers or correlation data (e.g., user IDs, tenant IDs, feature flags) that are safe to be widely propagated. Consider scrubbing Baggage before calling third-party APIs.","message":"Do not put sensitive or personally identifiable information (PII) in Baggage. Baggage is automatically propagated across service boundaries, typically in HTTP headers, making it visible in transit and potentially to external third-party services.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Prioritize essential, lightweight correlation data for Baggage. If you need to propagate large amounts of data, consider alternative mechanisms that do not rely on HTTP headers, such as a dedicated context service or database.","message":"Baggage entries add to the size of HTTP headers. Keep Baggage keys and values concise and limit the number of entries to avoid exceeding header size limits imposed by load balancers, proxies, or web servers, which can lead to request failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware that Baggage values are not immutable guarantees. If you require strict immutability or access control for propagated context, consider alternative patterns or implement custom validation in consuming services.","message":"Baggage is mutable by any service in the request chain. There is no built-in access control, meaning a downstream service could unintentionally or maliciously modify or remove Baggage entries set by upstream services.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure you explicitly add `BaggageSpanProcessor` (or `BaggageLogRecordProcessor` for logs) to your `TracerProvider` (or `LoggerProvider`) if you intend for Baggage items to appear as attributes on your telemetry. If you need fine-grained control, provide a custom predicate to the processor.","message":"Baggage is distinct from span attributes. Without a processor like `BaggageSpanProcessor`, Baggage entries are not automatically added to spans. They are propagated in the context but won't appear on the trace unless explicitly added.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}