wip

Author: realark

py/src/braintrust/__init__.py

@@ -51,6 +51,13 @@ def is_equal(expected, output):
 # Check env var at import time for auto-instrumentation
 import os
 
+from .env import validate_id_config as _validate_id_config
+
+
+# Fail fast on mutually-exclusive ID configuration (e.g. BRAINTRUST_OTEL_COMPAT
+# together with BRAINTRUST_LEGACY_UUID_IDS) as early as possible on import.
+_validate_id_config()
+
 
 if os.getenv("BRAINTRUST_INSTRUMENT_THREADS", "").lower() in ("true", "1", "yes"):
     try:

py/src/braintrust/context.py

@@ -6,7 +6,7 @@
 from dataclasses import dataclass
 from typing import Any
 
-from .env import BraintrustEnv
+from .env import BraintrustEnv, validate_id_config
 
 
 @dataclass
@@ -120,6 +120,10 @@ def get_context_manager() -> ContextManager:
         Braintrust-only context manager by default.
     """
 
+    # Fail fast if the ID configuration is inconsistent (belt-and-suspenders for
+    # the import-time check, in case env vars were mutated after import).
+    validate_id_config()
+
     # Check if OTEL should be explicitly enabled via environment variable
     if BraintrustEnv.OTEL_COMPAT.get(False):
         try:

py/src/braintrust/env.py

@@ -163,3 +163,42 @@ class BraintrustEnv:
     ALL_PUBLISH_PAYLOADS_DIR = EnvVar("BRAINTRUST_ALL_PUBLISH_PAYLOADS_DIR", EnvParser.STRING)
     DISABLE_ATEXIT_FLUSH = EnvVar("BRAINTRUST_DISABLE_ATEXIT_FLUSH", EnvParser.BOOL)
     OTEL_COMPAT = EnvVar("BRAINTRUST_OTEL_COMPAT", EnvParser.BOOL)
+    # Opt out of the default OpenTelemetry-compatible hex span/trace IDs and use
+    # legacy UUID-based IDs (and V3 span-component export) instead.
+    LEGACY_UUID_IDS = EnvVar("BRAINTRUST_LEGACY_UUID_IDS", EnvParser.BOOL)
+
+
+class BraintrustEnvError(Exception):
+    """Raised when Braintrust environment variables are configured inconsistently."""
+
+
+def use_legacy_uuid_ids() -> bool:
+    """Return True if the SDK should generate legacy UUID-based span/trace IDs.
+
+    The default is OpenTelemetry-compatible hex IDs (16-byte trace id / 8-byte
+    span id) with V4 span-component export. Setting BRAINTRUST_LEGACY_UUID_IDS
+    opts back into UUID IDs with V3 export.
+
+    Note: BRAINTRUST_OTEL_COMPAT (which selects the OpenTelemetry context
+    manager) requires hex IDs, so it always forces hex regardless of this
+    function. The mutually-exclusive combination is rejected by
+    validate_id_config().
+    """
+    validate_id_config()
+    if BraintrustEnv.OTEL_COMPAT.get(False):
+        return False
+    return BraintrustEnv.LEGACY_UUID_IDS.get(False)
+
+
+def validate_id_config() -> None:
+    """Fail fast on mutually-exclusive ID configuration.
+
+    BRAINTRUST_OTEL_COMPAT requires OpenTelemetry-compatible hex IDs, while
+    BRAINTRUST_LEGACY_UUID_IDS forces legacy UUID IDs. They cannot both be set.
+    """
+    if BraintrustEnv.OTEL_COMPAT.get(False) and BraintrustEnv.LEGACY_UUID_IDS.get(False):
+        raise BraintrustEnvError(
+            "BRAINTRUST_OTEL_COMPAT and BRAINTRUST_LEGACY_UUID_IDS are mutually "
+            "exclusive: OTEL compatibility requires hex span IDs, but legacy mode "
+            "forces UUID span IDs. Unset one of them."
+        )

py/src/braintrust/id_gen.py

@@ -2,17 +2,19 @@
 import uuid
 from abc import ABC, abstractmethod
 
-from .env import BraintrustEnv
+from .env import use_legacy_uuid_ids
 
 
 def get_id_generator():
     """Factory function that creates a new ID generator instance each time.
 
     This eliminates global state and makes tests parallelizable.
     Each caller gets their own generator instance.
+
+    Defaults to OpenTelemetry-compatible hex IDs. Set BRAINTRUST_LEGACY_UUID_IDS
+    to opt back into legacy UUID-based IDs.
     """
-    use_otel = BraintrustEnv.OTEL_COMPAT.get(False)
-    return OTELIDGenerator() if use_otel else UUIDGenerator()
+    return UUIDGenerator() if use_legacy_uuid_ids() else OTELIDGenerator()
 
 
 class IDGenerator(ABC):

py/src/braintrust/logger.py

@@ -52,7 +52,7 @@
     TRANSACTION_ID_FIELD,
     VALID_SOURCES,
 )
-from .env import BraintrustEnv
+from .env import BraintrustEnv, use_legacy_uuid_ids
 from .generated_types import (
     AttachmentReference,
     AttachmentStatus,
@@ -71,6 +71,17 @@
 from .prompt_cache.lru_cache import LRUCache
 from .prompt_cache.parameters_cache import ParametersCache
 from .prompt_cache.prompt_cache import PromptCache
+from .propagation import (
+    BAGGAGE_HEADER,
+    BRAINTRUST_PARENT_KEY,
+    BT_PARENT_HEADER,
+    TRACEPARENT_HEADER,
+    format_baggage,
+    format_traceparent,
+    get_header,
+    parse_baggage,
+    parse_traceparent,
+)
 from .queue import DEFAULT_QUEUE_SIZE, LogQueue
 from .serializable_data_class import SerializableDataClass
 from .span_identifier_v3 import SpanComponentsV3, SpanObjectTypeV3
@@ -146,9 +157,14 @@ class ParametersRef(TypedDict, total=False):
 
 
 def _get_exporter():
-    """Return the active exporter (e.g. the version of SpanComponentsv*)"""
-    use_v4 = BraintrustEnv.OTEL_COMPAT.get(False)
-    return SpanComponentsV4 if use_v4 else SpanComponentsV3
+    """Return the active exporter (e.g. the version of SpanComponentsv*).
+
+    The export version is coupled to the active ID format: hex IDs (the default)
+    serialize as V4, legacy UUID IDs serialize as V3. These must move together --
+    serializing hex IDs via V3 would lose the compact encoding and risk
+    corrupting hex values that happen to parse as UUIDs.
+    """
+    return SpanComponentsV3 if use_legacy_uuid_ids() else SpanComponentsV4
 
 
 class Exportable(ABC):
@@ -224,6 +240,15 @@ def export(self) -> str:
         :returns: Serialized representation of this span's identifiers.
         """
 
+    @abstractmethod
+    def inject(self, carrier: dict | None = None) -> dict:
+        """
+        Inject W3C trace-context headers (`traceparent` and `baggage`) for this span into a carrier dict, for distributed tracing across service boundaries.
+
+        :param carrier: Optional existing carrier (e.g. outbound HTTP headers) to mutate. A new dict is created if omitted.
+        :returns: The carrier dict with propagation headers injected.
+        """
+
     @abstractmethod
     def link(self) -> str:
         """
@@ -341,6 +366,9 @@ def end(self, end_time: float | None = None) -> float:
     def export(self):
         return ""
 
+    def inject(self, carrier: dict | None = None) -> dict:
+        return carrier if carrier is not None else {}
+
     def link(self) -> str:
         return NOOP_SPAN_PERMALINK
 
@@ -2388,6 +2416,180 @@ def get_span_parent_object(
     return NOOP_SPAN
 
 
+def _current_braintrust_parent(state: BraintrustState | None = None) -> str | None:
+    """Return the Braintrust parent string for the current logger/experiment, if any.
+
+    Used as the fallback Braintrust parent on receive, when an inbound request
+    carries trace identity (`traceparent`) but no `braintrust.parent` baggage.
+    """
+    if state is None:
+        state = _state
+
+    experiment = current_experiment()
+    if experiment:
+        try:
+            components = SpanComponentsV4.from_str(experiment.export())
+            return f"experiment_id:{components.object_id}"
+        except Exception:
+            return None
+
+    logger = current_logger()
+    if logger:
+        try:
+            components = SpanComponentsV4.from_str(logger.export())
+            if components.object_id:
+                return f"project_id:{components.object_id}"
+            meta = components.compute_object_metadata_args or {}
+            name = meta.get("project_name")
+            if name:
+                return f"project_name:{name}"
+        except Exception:
+            return None
+
+    return None
+
+
+def _braintrust_parent_to_components(braintrust_parent: str):
+    """Parse a `braintrust.parent` string into (object_type, object_id, compute_args).
+
+    Accepts `project_id:<id>`, `project_name:<name>`, or `experiment_id:<id>`.
+    Returns None if the value is empty or malformed.
+    """
+    if not braintrust_parent:
+        return None
+    if braintrust_parent.startswith("project_id:"):
+        object_id = braintrust_parent[len("project_id:") :]
+        return (SpanObjectTypeV3.PROJECT_LOGS, object_id, None) if object_id else None
+    if braintrust_parent.startswith("project_name:"):
+        name = braintrust_parent[len("project_name:") :]
+        return (SpanObjectTypeV3.PROJECT_LOGS, None, {"project_name": name}) if name else None
+    if braintrust_parent.startswith("experiment_id:"):
+        object_id = braintrust_parent[len("experiment_id:") :]
+        return (SpanObjectTypeV3.EXPERIMENT, object_id, None) if object_id else None
+    return None
+
+
+def _inject_into_carrier(carrier: dict, trace_id: str, span_id: str, braintrust_parent: str | None) -> None:
+    """Inject W3C trace-context headers into a carrier dict (in place).
+
+    Emits `traceparent` from the hex trace/span ids, and merges
+    `braintrust.parent` into existing `baggage` when known. Pre-existing,
+    non-Braintrust baggage entries are preserved. Never emits `x-bt-parent`.
+    """
+    traceparent = format_traceparent(trace_id, span_id)
+    if traceparent is None:
+        # Ids aren't W3C-shaped (e.g. legacy UUID mode); nothing to propagate.
+        return
+    carrier[TRACEPARENT_HEADER] = traceparent
+
+    # Merge braintrust.parent into any existing baggage, preserving other keys.
+    existing = get_header(carrier, BAGGAGE_HEADER)
+    entries = parse_baggage(existing) if existing else {}
+    if braintrust_parent:
+        entries[BRAINTRUST_PARENT_KEY] = braintrust_parent
+    baggage_value = format_baggage(entries)
+    if baggage_value is not None:
+        carrier[BAGGAGE_HEADER] = baggage_value
+
+
+def inject_trace_context(carrier: dict | None = None, span: "Span | None" = None) -> dict:
+    """Inject W3C trace-context headers for the current (or given) span into a carrier.
+
+    This is the free-function form of `Span.inject`, and the send-side
+    counterpart of `extract_trace_context`. If no span is provided, the
+    currently-active span is used. Propagation is best-effort and never raises.
+
+    :param carrier: Optional carrier dict (e.g. outbound HTTP headers) to mutate.
+    :param span: Optional span to inject. Defaults to the current span.
+    :returns: The carrier with propagation headers injected.
+    """
+    if carrier is None:
+        carrier = {}
+    span = span if span is not None else current_span()
+    try:
+        return span.inject(carrier)
+    except Exception as e:
+        logging.warning(f"Error injecting trace context: {e}")
+        return carrier
+
+
+def extract_trace_context(headers: dict, default_parent: str | None = None) -> str | None:
+    """Resolve a Braintrust `parent` string from inbound trace-context headers.
+
+    This is the receive-side counterpart of `Span.inject` /
+    `inject_trace_context`. The returned value can be passed as `parent=` to
+    `start_span`.
+
+    Resolution priority (per the distributed-tracing spec):
+
+    1. A valid W3C `traceparent` establishes trace identity. The Braintrust
+       container is read from `braintrust.parent` in `baggage`; if absent, it
+       falls back to `default_parent`, then to the SDK's configured current
+       logger/experiment.
+    2. Otherwise, the deprecated `x-bt-parent` header (a span slug) is decoded.
+    3. Otherwise, returns None (caller should start a fresh root span).
+
+    When both `traceparent` and `x-bt-parent` are present, `traceparent` wins.
+    Header lookups are case-insensitive. Malformed headers are treated as absent.
+
+    :param headers: Inbound carrier (e.g. HTTP request headers).
+    :param default_parent: Braintrust parent string to use when trace identity is
+        present but no `braintrust.parent` baggage was provided.
+    :returns: An opaque parent string for `start_span(parent=...)`, or None.
+    """
+    if not headers:
+        return None
+
+    traceparent = get_header(headers, TRACEPARENT_HEADER)
+    parsed = parse_traceparent(traceparent) if traceparent else None
+
+    if parsed is not None:
+        trace_id, span_id = parsed
+
+        # Determine the Braintrust container: baggage -> default_parent -> current.
+        braintrust_parent = None
+        baggage_value = get_header(headers, BAGGAGE_HEADER)
+        if baggage_value:
+            braintrust_parent = parse_baggage(baggage_value).get(BRAINTRUST_PARENT_KEY)
+        if not braintrust_parent:
+            braintrust_parent = default_parent or _current_braintrust_parent()
+        if not braintrust_parent:
+            logging.warning(
+                "Received traceparent without a braintrust.parent and no default parent is "
+                "configured; cannot route the trace. Configure a logger/experiment or pass "
+                "default_parent."
+            )
+            return None
+
+        parsed_parent = _braintrust_parent_to_components(braintrust_parent)
+        if parsed_parent is None:
+            logging.warning(f"Invalid braintrust.parent: {braintrust_parent!r}")
+            return None
+        object_type, object_id, compute_args = parsed_parent
+
+        return SpanComponentsV4(
+            object_type=object_type,
+            object_id=object_id,
+            compute_object_metadata_args=compute_args,
+            row_id="bt-propagation",  # non-empty to enable span_id/root_span_id
+            span_id=span_id,
+            root_span_id=trace_id,
+        ).to_str()
+
+    # No valid traceparent: fall back to the deprecated x-bt-parent slug.
+    bt_parent = get_header(headers, BT_PARENT_HEADER)
+    if bt_parent:
+        try:
+            # Validate it decodes; pass through opaquely if so.
+            SpanComponentsV4.from_str(bt_parent)
+            return bt_parent
+        except Exception:
+            logging.warning("Malformed x-bt-parent header; ignoring.")
+            return None
+
+    return None
+
+
 def _try_log_input(span, f_sig, f_args, f_kwargs):
     if f_sig:
         input_data = f_sig.bind(*f_args, **f_kwargs).arguments
@@ -4374,9 +4576,9 @@ def export(self) -> str:
             object_id = self.parent_object_id.get()
             compute_object_metadata_args = None
 
-        # Choose SpanComponents version based on BRAINTRUST_OTEL_COMPAT env var
-        use_v4 = BraintrustEnv.OTEL_COMPAT.get(False)
-        span_components_class = SpanComponentsV4 if use_v4 else SpanComponentsV3
+        # Choose SpanComponents version based on the active ID format (hex -> V4,
+        # legacy UUID -> V3). Coupled via _get_exporter() so the two never desync.
+        span_components_class = _get_exporter()
 
         # Disable span cache since remote function spans won't be in the local cache
         self.state.span_cache.disable()
@@ -4391,6 +4593,32 @@ def export(self) -> str:
             propagated_event=self.propagated_event,
         ).to_str()
 
+    def inject(self, carrier: dict | None = None) -> dict:
+        """Inject W3C trace-context headers for this span into a carrier dict.
+
+        Adds ``traceparent`` (trace identity) and, when this span's Braintrust
+        parent is known, a ``baggage`` entry ``braintrust.parent=<parent>``
+        (merged with any pre-existing baggage). Propagation is best-effort and
+        never raises; if the span's ids are not W3C-shaped hex (e.g. legacy UUID
+        mode), ``traceparent`` is omitted.
+
+        :param carrier: Optional existing carrier (e.g. outbound HTTP headers) to
+            mutate and return. A new dict is created if not provided.
+        :returns: The carrier dict with propagation headers injected.
+        """
+        if carrier is None:
+            carrier = {}
+        try:
+            _inject_into_carrier(
+                carrier,
+                trace_id=self.root_span_id,
+                span_id=self.span_id,
+                braintrust_parent=self._get_otel_parent(),
+            )
+        except Exception as e:  # best-effort: never break the caller
+            logging.warning(f"Error injecting trace context: {e}")
+        return carrier
+
     def link(self) -> str:
         parent_type, info = self._get_parent_info()
         if parent_type == SpanObjectTypeV3.PROJECT_LOGS: