feat(sdk): add W3C agent trace propagation helpers

Author: Whxuan0701

packages/traceloop-sdk/README.md

@@ -2,6 +2,20 @@
 
 Traceloop’s Python SDK allows you to easily start monitoring and debugging your LLM execution. Tracing is done in a non-intrusive way, built on top of OpenTelemetry. You can choose to export the traces to Traceloop, or to your existing observability stack.
 
+For agent-to-agent HTTP calls, use the opt-in W3C helpers to carry the current
+trace across service boundaries:
+
+```python
+from traceloop.sdk import inject_trace_context, extract_trace_context
+
+headers = inject_trace_context()
+remote_context = extract_trace_context(request.headers)
+```
+
+`Traceloop.init()` configures W3C Trace Context and Baggage propagation by
+default. Existing custom propagators passed through `propagator=` remain
+supported.
+
 ```python
 Traceloop.init(app_name="joke_generation_service")
 

packages/traceloop-sdk/tests/test_propagation.py

@@ -0,0 +1,36 @@
+from opentelemetry import context, trace
+from opentelemetry.sdk.trace import TracerProvider
+
+from traceloop.sdk.propagation import extract_trace_context, inject_trace_context
+
+
+def test_inject_and_extract_trace_context_round_trip():
+    provider = TracerProvider()
+    tracer = provider.get_tracer("test")
+    carrier = {}
+
+    with tracer.start_as_current_span("parent") as span:
+        inject_trace_context(carrier)
+        extracted = extract_trace_context(carrier)
+        extracted_span = trace.get_current_span(extracted)
+
+        assert carrier["traceparent"].startswith("00-")
+        assert f"-{span.get_span_context().span_id:016x}-" in carrier["traceparent"]
+        assert extracted_span.get_span_context().trace_id == span.get_span_context().trace_id
+
+
+def test_inject_accepts_an_existing_carrier():
+    carrier = {"x-request-id": "request-1"}
+    result = inject_trace_context(carrier)
+
+    assert result is carrier
+    assert result["x-request-id"] == "request-1"
+
+
+def test_extract_does_not_mutate_current_context():
+    carrier = {}
+    current = context.get_current()
+
+    extracted = extract_trace_context(carrier)
+
+    assert extracted is not current

packages/traceloop-sdk/traceloop/sdk/__init__.py

@@ -33,6 +33,10 @@
 from typing import Dict
 from traceloop.sdk.client.client import Client
 from traceloop.sdk.associations.associations import AssociationProperty as AssociationProperty
+from traceloop.sdk.propagation import (
+    extract_trace_context as extract_trace_context,
+    inject_trace_context as inject_trace_context,
+)
 
 
 class Traceloop:

packages/traceloop-sdk/traceloop/sdk/propagation.py

@@ -0,0 +1,19 @@
+"""Opt-in W3C trace-context helpers for agent-to-agent calls."""
+
+from typing import Any, MutableMapping
+
+from opentelemetry import propagate
+from opentelemetry.context import Context
+
+
+def inject_trace_context(carrier: MutableMapping[str, Any] | None = None) -> MutableMapping[str, Any]:
+    """Inject the current W3C trace context into an HTTP-like carrier."""
+    target: MutableMapping[str, Any] = carrier if carrier is not None else {}
+    propagate.inject(target)
+    return target
+
+
+def extract_trace_context(carrier: Any) -> Context:
+    """Extract a remote W3C trace context without changing the current context."""
+    return propagate.extract(carrier)
+

packages/traceloop-sdk/traceloop/sdk/tracing/tracing.py

@@ -17,6 +17,9 @@
 from opentelemetry.sdk.trace.sampling import Sampler
 from opentelemetry.propagators.textmap import TextMapPropagator
 from opentelemetry.propagate import set_global_textmap
+from opentelemetry.propagators.composite import CompositePropagator
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+from opentelemetry.baggage.propagation import W3CBaggagePropagator
 from opentelemetry.sdk.trace.export import (
     SpanExporter,
     SimpleSpanProcessor,
@@ -162,8 +165,12 @@ def wrapped_on_end(span):
                 obj.__spans_processor.on_start = obj._span_processor_on_start
                 obj.__tracer_provider.add_span_processor(obj.__spans_processor)
 
-            if propagator:
-                set_global_textmap(propagator)
+            set_global_textmap(
+                propagator
+                or CompositePropagator(
+                    [TraceContextTextMapPropagator(), W3CBaggagePropagator()]
+                )
+            )
 
             # this makes sure otel context is propagated so we always want it
             ThreadingInstrumentor().instrument()