fixup

Author: realark

py/src/braintrust/logger.py

@@ -2478,6 +2478,22 @@ def _braintrust_parent_to_components(braintrust_parent: str):
     return None
 
 
+def _set_header(carrier: dict, name: str, value: str) -> None:
+    """Set a W3C trace-context header on a carrier, sending the lowercase name.
+
+    Per the W3C Trace Context spec (§3.2.1 / §3.3.1), vendors SHOULD send these
+    header names in lowercase. ``name`` is always the canonical lowercase key.
+    A plain ``dict`` carrier is case-sensitive, so any pre-existing case-variant
+    (e.g. ``Baggage`` from a framework that title-cases headers) must be removed
+    first, otherwise the carrier would end up with two conflicting headers.
+    """
+    lowered = name.lower()
+    for key in list(carrier.keys()):
+        if isinstance(key, str) and key != name and key.lower() == lowered:
+            del carrier[key]
+    carrier[name] = value
+
+
 def _inject_into_carrier(
     carrier: dict,
     trace_id: str,
@@ -2496,11 +2512,11 @@ def _inject_into_carrier(
     if traceparent is None:
         # Ids aren't W3C-shaped (e.g. legacy UUID mode); nothing to propagate.
         return
-    carrier[TRACEPARENT_HEADER] = traceparent
+    _set_header(carrier, TRACEPARENT_HEADER, traceparent)
 
     # Forward upstream tracestate (per W3C, only alongside a valid traceparent).
     if tracestate:
-        carrier[TRACESTATE_HEADER] = tracestate
+        _set_header(carrier, TRACESTATE_HEADER, tracestate)
 
     # Merge braintrust.parent into any existing baggage, preserving other keys.
     existing = get_header(carrier, BAGGAGE_HEADER)
@@ -2509,7 +2525,7 @@ def _inject_into_carrier(
         entries[BRAINTRUST_PARENT_KEY] = braintrust_parent
     baggage_value = format_baggage(entries)
     if baggage_value is not None:
-        carrier[BAGGAGE_HEADER] = baggage_value
+        _set_header(carrier, BAGGAGE_HEADER, baggage_value)
 
 
 def inject_trace_context(carrier: dict | None = None, span: "Span | None" = None) -> dict:
@@ -2838,9 +2854,13 @@ def start_span(
         # Resolve tracestate from the same source the parent object came from
         # (the explicit `parent` arg, or the ambient current_parent).
         _slug, tracestate = _normalize_parent(parent if parent is not None else state.current_parent.get())
-        if parent_obj.row_id and parent_obj.span_id and parent_obj.root_span_id:
+        if parent_obj.row_id and _parent_span_ids_match_active_format(parent_obj.span_id, parent_obj.root_span_id):
             parent_span_ids = ParentSpanIds(span_id=parent_obj.span_id, root_span_id=parent_obj.root_span_id)
         else:
+            # Either no row id, or the parent slug carries ids in a format that
+            # doesn't match the active ID format (e.g. legacy UUID ids while
+            # running in the default hex mode). Drop the span linkage and start a
+            # fresh root, keeping the object routing from the slug.
             parent_span_ids = None
         return SpanImpl(
             parent_object_type=parent_obj.object_type,

py/src/braintrust/otel/__init__.py

@@ -725,8 +725,3 @@ def parent_from_headers(headers: dict[str, str], propagator=None) -> str | None:
     )
 
     return components.to_str()
-
-
-# Alias matching the native propagation naming (`braintrust.extract_trace_context`).
-# `parent_from_headers` is retained as the historical name.
-extract_trace_context = parent_from_headers

py/src/braintrust/propagation.py

@@ -8,23 +8,16 @@
 Trace identity (trace id + parent span id) is carried in ``traceparent``; the
 Braintrust container the trace belongs to (project/experiment) is carried in
 ``baggage`` under the ``braintrust.parent`` key.
-
-The deprecated ``x-bt-parent`` header (a serialized span slug) is accepted on
-receive for backwards compatibility with older native SDKs, but is never
-emitted -- ``traceparent`` takes priority whenever both are present.
 """
 
 import logging
 import re
 
-from .http_headers import BT_PARENT
-
 
 __all__ = [
     "TRACEPARENT_HEADER",
     "TRACESTATE_HEADER",
     "BAGGAGE_HEADER",
-    "BT_PARENT_HEADER",
     "BRAINTRUST_PARENT_KEY",
     "parse_traceparent",
     "format_traceparent",
@@ -38,7 +31,6 @@
 TRACEPARENT_HEADER = "traceparent"
 TRACESTATE_HEADER = "tracestate"
 BAGGAGE_HEADER = "baggage"
-BT_PARENT_HEADER = BT_PARENT  # "x-bt-parent"
 BRAINTRUST_PARENT_KEY = "braintrust.parent"
 
 # W3C traceparent: version-traceid-parentid-flags, version 00, lowercase hex.

py/src/braintrust/test_propagation.py

@@ -154,6 +154,33 @@ def test_preexisting_baggage_preserved(self, memory_and_logger):
         assert parsed["team"] == "eng"
         assert parsed[BRAINTRUST_PARENT_KEY] == "project_name:propagation-test"
 
+    def test_title_cased_baggage_emits_single_lowercase_header(self, memory_and_logger):
+        # Per W3C (§3.3.1) the header name SHOULD be sent lowercase. A carrier
+        # that arrives with a title-cased `Baggage` (e.g. from a framework that
+        # normalizes header casing) must be rewritten to a single lowercase
+        # `baggage` key, not left with two conflicting case-variants.
+        _mem, logger = memory_and_logger
+        with logger.start_span(name="svc_a") as span:
+            carrier = span.inject({"Baggage": "user=alice"})
+
+        baggage_keys = [k for k in carrier if k.lower() == BAGGAGE_HEADER]
+        assert baggage_keys == [BAGGAGE_HEADER]
+        parsed = parse_baggage(carrier[BAGGAGE_HEADER])
+        assert parsed["user"] == "alice"
+        assert parsed[BRAINTRUST_PARENT_KEY] == "project_name:propagation-test"
+
+    def test_title_cased_traceparent_emits_single_lowercase_header(self, memory_and_logger):
+        # A pre-existing title-cased `Traceparent` must be replaced by a single
+        # lowercase `traceparent` (W3C §3.2.1), with no stale variant remaining.
+        _mem, logger = memory_and_logger
+        with logger.start_span(name="svc_a") as span:
+            carrier = span.inject({"Traceparent": "stale"})
+
+        traceparent_keys = [k for k in carrier if k.lower() == TRACEPARENT_HEADER]
+        assert traceparent_keys == [TRACEPARENT_HEADER]
+        tp = parse_traceparent(carrier[TRACEPARENT_HEADER])
+        assert tp == (span.root_span_id, span.span_id)
+
     def test_never_emits_x_bt_parent(self, memory_and_logger):
         _mem, logger = memory_and_logger
         with logger.start_span(name="svc_a") as span:
@@ -371,6 +398,32 @@ def test_legacy_parent_slug_ignored_in_hex_mode():
             assert not child.span_parents
 
 
+def test_legacy_parent_slug_ignored_in_hex_mode_toplevel_start_span():
+    # Same as above, but through the module-level `start_span`, which resolves
+    # the parent slug independently of `Logger.start_span` and must apply the
+    # same format-mismatch guard.
+    import uuid
+
+    from braintrust.logger import start_span
+    from braintrust.span_identifier_v3 import SpanComponentsV3
+
+    legacy_slug = SpanComponentsV3(
+        object_type=SpanObjectTypeV3.PROJECT_LOGS,
+        object_id="legacy-proj",
+        row_id=str(uuid.uuid4()),
+        span_id=str(uuid.uuid4()),
+        root_span_id=str(uuid.uuid4()),
+    ).to_str()
+
+    with _internal_with_memory_background_logger():
+        init_test_logger("legacy-proj")
+        with start_span(name="child", parent=legacy_slug) as child:
+            # Fresh hex root: hex-shaped ids, no parent linkage.
+            assert len(child.span_id) == 16
+            assert len(child.root_span_id) == 32
+            assert not child.span_parents
+
+
 # --------------------------------------------------------------------------- #
 # tracestate pass-through (W3C: forward upstream vendor state)
 # --------------------------------------------------------------------------- #