implement w3c distributed tracing

implements the `distributed-tracing` sdk spec

- default span/trace id gen to use otel-friendly 16/8 byte hex IDs
- new inject/extract tools for w3c headers

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/functions/invoke.py

@@ -5,7 +5,7 @@
 
 from .._generated_types import FunctionTypeEnum
 from ..bt_json import bt_dumps
-from ..logger import Exportable, _internal_get_global_state, get_span_parent_object, login, proxy_conn
+from ..logger import Exportable, _get_span_parent_object, _internal_get_global_state, login, proxy_conn
 from ..types import Metadata
 from ..util import response_raise_for_status
 from .constants import INVOKE_API_VERSION
@@ -163,7 +163,7 @@ def invoke(
         force_login=force_login,
     )
 
-    parent = parent if isinstance(parent, str) else parent.export() if parent else get_span_parent_object().export()
+    parent = parent if isinstance(parent, str) else parent.export() if parent else _get_span_parent_object().export()
 
     function_id_args = {}
     if function_id is not None:

py/src/braintrust/functions/test_invoke.py

@@ -74,7 +74,7 @@ def _invoke_with_messages(messages):
 
     with (
         patch("braintrust.functions.invoke.login"),
-        patch("braintrust.functions.invoke.get_span_parent_object") as mock_parent,
+        patch("braintrust.functions.invoke._get_span_parent_object") as mock_parent,
         patch("braintrust.functions.invoke.proxy_conn", return_value=mock_conn),
     ):
         mock_parent.return_value.export.return_value = "span-export"

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):