Keep the W3C traceparent shorthand working under any OTEL_PROPAGATORS

The bare-string form of airflow/dagrun_parent_trace_context is documented as a
W3C traceparent -- its value syntax, not just its key name -- so routing it
through the configured propagators made a documented input silently produce a
root trace on any deployment whose propagator set omits tracecontext.

Author: rjgoyln

airflow-core/docs/administration-and-deployment/logging-monitoring/traces.rst

@@ -135,9 +135,12 @@ run — from the UI/API "Trigger with config" dialog, the ``airflow dags trigger
 
         {"airflow/dagrun_parent_trace_context": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"}
 
-    A carrier mapping is read by the configured propagators, so under the default
-    ``OTEL_PROPAGATORS=tracecontext,baggage`` it accepts ``traceparent``, ``tracestate`` and
-    ``baggage``, and a deployment running a vendor propagator can supply that propagator's own keys.
+    The two forms are read differently, on purpose. The bare-string shorthand is *defined* as a W3C
+    ``traceparent`` — its value syntax, not just its key name — so it is always parsed as one,
+    regardless of ``OTEL_PROPAGATORS``. A carrier mapping is read by the configured propagators
+    instead, so under the default ``OTEL_PROPAGATORS=tracecontext,baggage`` it accepts
+    ``traceparent``, ``tracestate`` and ``baggage``, and a deployment running a vendor propagator can
+    supply that propagator's own keys. Use the mapping form when you are not propagating W3C.
 
     .. code-block:: json
 

airflow-core/src/airflow/models/dagrun.py

@@ -31,6 +31,7 @@
 from opentelemetry import propagate, trace
 from opentelemetry.context import context
 from opentelemetry.trace import StatusCode
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
 from sqlalchemy import (
     JSON,
     Enum,
@@ -220,15 +221,20 @@ def parent_trace_context(conf) -> context.Context | None:
         return None
     match conf.get(DAGRUN_PARENT_TRACE_CONTEXT_KEY):
         case str() as traceparent:
+            # The shorthand's *value* syntax is W3C, not just its key name, so it keeps
+            # being parsed as W3C whatever OTEL_PROPAGATORS says -- handing it to a
+            # propagator expecting another format would silently drop the parent.
+            extract = TraceContextTextMapPropagator().extract
             carrier = {"traceparent": traceparent}
         case dict() as raw:
             # Keep only str members: a non-str tracestate reaches TraceState.from_header
             # unvalidated and raises TypeError, which would drop the otherwise-valid parent.
+            extract = propagate.extract
             carrier = {k: v for k, v in raw.items() if isinstance(v, str)}
         case _:
             return None
     try:
-        ctx = propagate.extract(carrier)
+        ctx = extract(carrier)
     except Exception:
         # Never let a malformed conf value fail run creation; fall back to a root trace.
         return None

airflow-core/tests/unit/models/test_dagrun.py

@@ -4265,15 +4265,65 @@ def test_parent_trace_context_carrier_read_by_configured_propagators():
     assert baggage.get_all(ctx) == {"tenant": "acme"}
 
 
-@mock.patch("airflow.models.dagrun.propagate.extract", side_effect=ValueError("boom"))
-def test_parent_trace_context_swallows_propagator_error(mock_extract):
-    """A propagator failure degrades to a root trace instead of failing run creation."""
+@pytest.fixture
+def global_propagator_without_tracecontext():
+    """Stand in for a deployment whose OTEL_PROPAGATORS does not include ``tracecontext``."""
+    from opentelemetry import propagate
+    from opentelemetry.baggage.propagation import W3CBaggagePropagator
+    from opentelemetry.propagators.composite import CompositePropagator
+
+    original = propagate.get_global_textmap()
+    propagate.set_global_textmap(CompositePropagator([W3CBaggagePropagator()]))
+    yield
+    propagate.set_global_textmap(original)
+
+
+def test_parent_trace_context_string_shorthand_ignores_configured_propagators(
+    global_propagator_without_tracecontext,
+):
+    """The bare-string shorthand is a W3C traceparent by definition, so OTEL_PROPAGATORS cannot break it."""
     from airflow.models.dagrun import parent_trace_context
 
     conf = {DAGRUN_PARENT_TRACE_CONTEXT_KEY: f"00-{_EXTERNAL_TRACE_ID}-{_EXTERNAL_SPAN_ID}-01"}
+    span_ctx = otel_trace.get_current_span(parent_trace_context(conf)).get_span_context()
+    assert format(span_ctx.trace_id, "032x") == _EXTERNAL_TRACE_ID
+
+
+def test_parent_trace_context_carrier_mapping_follows_configured_propagators(
+    global_propagator_without_tracecontext,
+):
+    """The mapping form is the propagator-agnostic path, so a W3C-less propagator set drops it."""
+    from airflow.models.dagrun import parent_trace_context
+
+    conf = {
+        DAGRUN_PARENT_TRACE_CONTEXT_KEY: {"traceparent": f"00-{_EXTERNAL_TRACE_ID}-{_EXTERNAL_SPAN_ID}-01"}
+    }
     assert parent_trace_context(conf) is None
 
 
+@pytest.mark.parametrize(
+    ("conf_value", "patch_target"),
+    [
+        pytest.param(
+            f"00-{_EXTERNAL_TRACE_ID}-{_EXTERNAL_SPAN_ID}-01",
+            "airflow.models.dagrun.TraceContextTextMapPropagator.extract",
+            id="string-shorthand",
+        ),
+        pytest.param(
+            {"traceparent": f"00-{_EXTERNAL_TRACE_ID}-{_EXTERNAL_SPAN_ID}-01"},
+            "airflow.models.dagrun.propagate.extract",
+            id="carrier-mapping",
+        ),
+    ],
+)
+def test_parent_trace_context_swallows_propagator_error(conf_value, patch_target):
+    """A propagator failure degrades to a root trace instead of failing run creation."""
+    from airflow.models.dagrun import parent_trace_context
+
+    with mock.patch(patch_target, side_effect=ValueError("boom")):
+        assert parent_trace_context({DAGRUN_PARENT_TRACE_CONTEXT_KEY: conf_value}) is None
+
+
 class TestDagRunTracing:
     """Tests for DagRun OpenTelemetry span behavior."""