Context Propagation & Baggage
Relevant source files
The following files were used as context for generating this wiki page:
Context propagation is the mechanism by which Logfire transmits metadata, such as Trace IDs and Baggage, across service boundaries and execution contexts. This system ensures that distributed traces remain connected as requests move through different parts of a system. Baggage allows developers to attach arbitrary key-value pairs to a trace, which are then automatically carried along with the execution flow and can be added to span attributes.
In Logfire, context propagation is built on OpenTelemetry standards but includes specific safety behaviors, such as warnings for unintentional distributed tracing. Baggage attributes can be automatically injected into every span created within a specific context, providing consistent metadata across entire trace trees.
Distributed Tracing & Propagators
Logfire uses propagators to inject and extract trace context from carriers, typically HTTP headers like traceparent and baggage.
Propagation Control
The behavior of context extraction is controlled by the distributed_tracing configuration setting. Logfire provides specialized propagators to handle different levels of trust and intentionality:
- WarnOnExtractTraceContextPropagator: The default behavior. It extracts context but issues a
RuntimeWarningto alert developers to potentially unintentional distributed tracing. - NoExtractTraceContextPropagator: Suppresses the extraction of incoming trace context entirely, preventing external systems from influencing internal traces.
- CompositePropagator: Standard OpenTelemetry behavior where context is extracted without additional warnings.
Sources: logfire/_internal/config.py:734-747, tests/test_configure.py:1120-1135
Context Flow
The following diagram illustrates how context moves between execution environments using the propagation API.
The flow ensures that Service B's spans reference Service A's trace ID.
Sources: logfire/propagate.py:32-75, tests/test_configure.py:1138-1150
Baggage Management
Baggage allows for the storage and propagation of arbitrary key-value pairs throughout a trace.
Configuration and Processors
Logfire includes a DirectBaggageAttributesSpanProcessor which automatically adds all current baggage entries to every span as attributes. This behavior is enabled by default but can be disabled using the add_baggage_to_attributes parameter in logfire.configure().
Sources: logfire/_internal/config.py:270-272, logfire/_internal/baggage.py:15-28
Key Functions
| Component | Description |
|---|---|
get_baggage() | Retrieves all baggage items in the current context as a dictionary. |
set_baggage(**kwargs) | A context manager that sets baggage for the duration of its block. |
DirectBaggageAttributesSpanProcessor | An internal span processor that reads baggage from the context and applies it to span attributes during the on_start phase. |
Sources: logfire/propagate.py:16-30, logfire/_internal/baggage.py:15-35
API Reference: Propagation Functions
Logfire provides a clean wrapper around OpenTelemetry's propagation and context APIs.
Context Carrier Format
The propagation functions interact with a ContextCarrier, which is defined as a dictionary of strings: dict[str, str].
Sources: logfire/propagate.py:13
Core Functions
get_context()
Retrieves the current trace context and baggage, returning them in a format suitable for HTTP headers.
Sources: logfire/propagate.py:32-49
attach_context(context, third_party=False)
A context manager that activates the provided context. If third_party is True, it uses the global textmap propagator directly; if False, it may trigger Logfire's internal warnings regarding unintentional tracing.
Sources: logfire/propagate.py:52-75
# Example Usage
import logfire
from logfire import propagate
with logfire.span('External Request'):
headers = propagate.get_context()
# Send headers with HTTP request...
# On the receiving side:
with propagate.attach_context(received_headers):
with logfire.span('Processing Request'):
pass
Sources: tests/test_configure.py:1127-1135, logfire/propagate.py:32-75
Implementation Details
The internal handling of baggage and context is tied to the SDKTracerProvider and specific span processors.
Span Processor Logic
The DirectBaggageAttributesSpanProcessor implements the on_start method to inject baggage into spans immediately upon creation. This ensures that even "pending" spans or short-lived spans capture the context available at their inception.
Configuration Options
The following table summarizes configuration parameters in logfire.configure() relevant to propagation and baggage.
| Parameter | Type | Default | Description |
|---|---|---|---|
distributed_tracing | bool | None | None | True enables full propagation; False disables extraction; None enables with warnings. |
add_baggage_to_attributes | bool | True | Whether to automatically add Baggage to spans as attributes. |
Sources: logfire/_internal/config.py:270-272, logfire/_internal/config.py:346-353
Conclusion
Context Propagation & Baggage in Logfire provides a robust framework for maintaining observability in distributed systems. By wrapping OpenTelemetry's complexity with simplified APIs like get_context() and set_baggage(), and providing safety features like WarnOnExtractTraceContextPropagator, Logfire ensures that traces remain consistent and developers are notified of potential configuration issues in their instrumentation.