clean up usage of preant context propogation

Author: nikhilc-microsoft

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/__init__.py

@@ -33,7 +33,7 @@
 from .tool_call_details import ToolCallDetails
 from .tool_type import ToolType
 from .trace_processor.span_processor import SpanProcessor
-from .utils import extract_trace_context
+from .utils import extract_context_from_headers, get_traceparent
 
 __all__ = [
     # Main SDK functions
@@ -73,7 +73,8 @@
     "InferenceOperationType",
     "ToolType",
     # Utility functions
-    "extract_trace_context",
+    "extract_context_from_headers",
+    "get_traceparent",
     # Constants
     # all constants from constants.py are exported via *
 ]

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/execute_tool_scope.py

@@ -47,7 +47,7 @@ def start(
             tenant_details: The details of the tenant
             request: Optional request details for additional context
             parent_context: Optional OpenTelemetry Context used to link this span to an
-                upstream operation. Use ``extract_trace_context()`` to convert a
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
                 Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object. Useful when
                 recording a tool call after execution has already completed.
@@ -90,7 +90,7 @@ def __init__(
             tenant_details: The details of the tenant
             request: Optional request details for additional context
             parent_context: Optional OpenTelemetry Context used to link this span to an
-                upstream operation. Use ``extract_trace_context()`` to convert a
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
                 Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object. Useful when
                 recording a tool call after execution has already completed.

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/inference_scope.py

@@ -50,7 +50,7 @@ def start(
             tenant_details: The details of the tenant
             request: Optional request details for additional context
             parent_context: Optional OpenTelemetry Context used to link this span to an
-                upstream operation. Use ``extract_trace_context()`` to convert a
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
                 Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.
@@ -80,7 +80,7 @@ def __init__(
             tenant_details: The details of the tenant
             request: Optional request details for additional context
             parent_context: Optional OpenTelemetry Context used to link this span to an
-                upstream operation. Use ``extract_trace_context()`` to convert a
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
                 Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/invoke_agent_scope.py

@@ -66,7 +66,7 @@ def start(
             caller_agent_details: Optional details of the caller agent
             caller_details: Optional details of the non-agentic caller
             parent_context: Optional OpenTelemetry Context used to link this span to an
-                upstream operation. Use ``extract_trace_context()`` to convert a
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
                 Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.
@@ -109,7 +109,7 @@ def __init__(
             caller_agent_details: Optional details of the caller agent
             caller_details: Optional details of the non-agentic caller
             parent_context: Optional OpenTelemetry Context used to link this span to an
-                upstream operation. Use ``extract_trace_context()`` to convert a
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
                 Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/opentelemetry_scope.py

@@ -114,7 +114,7 @@ def __init__(
             agent_details: Optional agent details
             tenant_details: Optional tenant details
             parent_context: Optional OpenTelemetry Context used to link this span to an
-                upstream operation. Use ``extract_trace_context()`` to extract a
+                upstream operation. Use ``extract_context_from_headers()`` to extract a
                 Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
                 Useful when recording an operation after it has already completed.
@@ -303,24 +303,19 @@ def get_context(self) -> Context | None:
             return set_span_in_context(self._span)
         return None
 
-    def inject_trace_context(self) -> dict[str, str]:
-        """Inject trace context headers for distributed tracing propagation.
+    def inject_context_to_headers(self) -> dict[str, str]:
+        """Inject this span's trace context into W3C HTTP headers.
 
-        This method returns a dictionary of headers containing the trace
-        context (traceparent and tracestate) that can be used to propagate
-        the current span's context to downstream services via HTTP headers
-        or other transport mechanisms.
-
-        The headers follow the W3C Trace Context specification and include:
-        - ``traceparent``: Contains version, trace-id, parent-id, and trace-flags
-        - ``tracestate``: Contains vendor-specific trace information (if any)
+        Returns a dictionary of headers containing ``traceparent`` and
+        optionally ``tracestate`` that can be forwarded to downstream services
+        or stored for later context propagation.
 
         Example usage:
 
         .. code-block:: python
 
             scope = OpenTelemetryScope(...)
-            headers = scope.inject_trace_context()
+            headers = scope.inject_context_to_headers()
             # Add headers to outgoing HTTP request
             requests.get("https://downstream-service/api", headers=headers)
 

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/spans_scopes/output_scope.py

@@ -36,7 +36,7 @@ def start(
             tenant_details: The details of the tenant
             response: The response details from the agent
             parent_context: Optional OpenTelemetry Context used to link this span to an
-                upstream operation. Use ``extract_trace_context()`` to convert a
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
                 Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.
@@ -64,7 +64,7 @@ def __init__(
             tenant_details: The details of the tenant
             response: The response details from the agent
             parent_context: Optional OpenTelemetry Context used to link this span to an
-                upstream operation. Use ``extract_trace_context()`` to convert a
+                upstream operation. Use ``extract_context_from_headers()`` to convert a
                 Context from HTTP headers containing W3C traceparent.
             start_time: Optional explicit start time as a datetime object.
             end_time: Optional explicit end time as a datetime object.

libraries/microsoft-agents-a365-observability-core/microsoft_agents_a365/observability/core/utils.py

@@ -30,11 +30,12 @@
 logger.addHandler(logging.NullHandler())
 
 
-def extract_trace_context(headers: dict[str, str]) -> context.Context:
-    """Extract trace context from HTTP headers.
+def extract_context_from_headers(headers: dict[str, str]) -> context.Context:
+    """Extract an OpenTelemetry Context from W3C trace HTTP headers.
 
-    This function extracts W3C Trace Context from a dictionary of HTTP headers
-    using OpenTelemetry's standard propagation mechanism.
+    Parses ``traceparent`` (and optionally ``tracestate``) headers and returns
+    an OpenTelemetry Context that can be passed as ``parent_context`` to any
+    scope's ``start()`` method.
 
     Args:
         headers: Dictionary of HTTP headers containing trace context.
@@ -51,7 +52,7 @@ def extract_trace_context(headers: dict[str, str]) -> context.Context:
             headers = {
                 "traceparent": "00-1234567890abcdef1234567890abcdef-abcdefabcdef1234-01"
             }
-            parent_context = extract_trace_context(headers)
+            parent_context = extract_context_from_headers(headers)
             with InferenceScope.start(
                 details, agent, tenant, parent_context=parent_context
             ):
@@ -60,6 +61,29 @@ def extract_trace_context(headers: dict[str, str]) -> context.Context:
     return extract(headers)
 
 
+def get_traceparent(headers: dict[str, str]) -> str | None:
+    """Return the W3C ``traceparent`` value from a headers dictionary.
+
+    Args:
+        headers: Dictionary of HTTP headers, typically obtained from
+            :meth:`OpenTelemetryScope.inject_context_to_headers`.
+
+    Returns:
+        The traceparent string (e.g.
+        ``"00-<trace-id>-<span-id>-<flags>"``), or ``None`` if the
+        key is not present.
+
+    Example::
+
+        .. code-block:: python
+
+            # Extract traceparent from incoming HTTP request headers
+            traceparent = get_traceparent(request.headers)
+            turn_context.turn_state[A365_PARENT_TRACEPARENT_KEY] = traceparent
+    """
+    return headers.get("traceparent")
+
+
 def safe_json_dumps(obj: Any, **kwargs: Any) -> str:
     return json.dumps(obj, default=str, ensure_ascii=False, **kwargs)
 

libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/__init__.py

@@ -10,12 +10,15 @@
     ObservabilityHostingManager,
     ObservabilityHostingOptions,
 )
-from .middleware.output_logging_middleware import A365_PARENT_SPAN_KEY, OutputLoggingMiddleware
+from .middleware.output_logging_middleware import (
+    A365_PARENT_TRACEPARENT_KEY,
+    OutputLoggingMiddleware,
+)
 
 __all__ = [
     "BaggageMiddleware",
     "OutputLoggingMiddleware",
-    "A365_PARENT_SPAN_KEY",
+    "A365_PARENT_TRACEPARENT_KEY",
     "ObservabilityHostingManager",
     "ObservabilityHostingOptions",
 ]

libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/middleware/__init__.py

@@ -3,12 +3,12 @@
 
 from .baggage_middleware import BaggageMiddleware
 from .observability_hosting_manager import ObservabilityHostingManager, ObservabilityHostingOptions
-from .output_logging_middleware import A365_PARENT_SPAN_KEY, OutputLoggingMiddleware
+from .output_logging_middleware import A365_PARENT_TRACEPARENT_KEY, OutputLoggingMiddleware
 
 __all__ = [
     "BaggageMiddleware",
     "OutputLoggingMiddleware",
-    "A365_PARENT_SPAN_KEY",
+    "A365_PARENT_TRACEPARENT_KEY",
     "ObservabilityHostingManager",
     "ObservabilityHostingOptions",
 ]

libraries/microsoft-agents-a365-observability-hosting/microsoft_agents_a365/observability/hosting/middleware/output_logging_middleware.py

@@ -24,16 +24,16 @@
 from microsoft_agents_a365.observability.core.models.response import Response
 from microsoft_agents_a365.observability.core.spans_scopes.output_scope import OutputScope
 from microsoft_agents_a365.observability.core.tenant_details import TenantDetails
-from microsoft_agents_a365.observability.core.utils import extract_trace_context
+from microsoft_agents_a365.observability.core.utils import extract_context_from_headers
 
 from ..scope_helpers.utils import (
     get_execution_type_pair,
 )
 
 logger = logging.getLogger(__name__)
 
-# TurnState key for the parent span reference (W3C traceparent string).
-A365_PARENT_SPAN_KEY = "A365ParentSpanId"
+# TurnState key for the parent trace context (W3C traceparent string).
+A365_PARENT_TRACEPARENT_KEY = "A365ParentTraceparent"
 
 
 def _derive_agent_details(context: TurnContext) -> AgentDetails | None:
@@ -110,7 +110,7 @@ def _derive_execution_type(context: TurnContext) -> str | None:
 class OutputLoggingMiddleware:
     """Middleware that creates :class:`OutputScope` spans for outgoing messages.
 
-    Links to a parent span when :data:`A365_PARENT_SPAN_KEY` is set in
+    Links to a parent span when :data:`A365_PARENT_TRACEPARENT_KEY` is set in
     ``turn_state``.
 
     **Privacy note:** Outgoing message content is captured verbatim as span
@@ -176,16 +176,15 @@ async def handler(
                 await send_next()
                 return
 
-            parent_id: str | None = turn_context.turn_state.get(A365_PARENT_SPAN_KEY)
+            traceparent: str | None = turn_context.turn_state.get(A365_PARENT_TRACEPARENT_KEY)
             parent_context = None
-            if parent_id:
-                # Convert W3C traceparent string to Context using OpenTelemetry's extract
-                parent_context = extract_trace_context({"traceparent": parent_id})
+            if traceparent:
+                parent_context = extract_context_from_headers({"traceparent": traceparent})
             else:
                 logger.warning(
-                    "[OutputLoggingMiddleware] No parent span ref in turn_state under "
+                    "[OutputLoggingMiddleware] No traceparent in turn_state under "
                     "'%s'. OutputScope will not be linked to a parent.",
-                    A365_PARENT_SPAN_KEY,
+                    A365_PARENT_TRACEPARENT_KEY,
                 )
 
             output_scope = OutputScope.start(