From 9feca45fb1dad37499c8bc69ddd91cdd92c5186b Mon Sep 17 00:00:00 2001
From: strawgate <williamseaston@gmail.com>
Date: Sat, 25 Apr 2026 19:11:57 -0500
Subject: [PATCH] Refine OTEL interop naming and docstrings

- Rename get_trace_context_carrier -> extract_propagation_keys_from_meta
  (carrier is OTEL jargon, new name is self-evident)
- Rename _get_ambient_span_context -> _get_ambient_or_current_span_context
  (makes fallback to current span explicit in name)
- Fix extract_trace_context docstring: merged -> propagated (precise)
- Trim duplicate wording in _initialize_session_with_meta docstring
---
 src/fastmcp/client/client.py    |  2 +-
 src/fastmcp/server/telemetry.py | 14 +++++++++-----
 src/fastmcp/telemetry.py        |  8 ++++----
 3 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/src/fastmcp/client/client.py b/src/fastmcp/client/client.py
index 325826f28..702fb553c 100644
--- a/src/fastmcp/client/client.py
+++ b/src/fastmcp/client/client.py
@@ -550,7 +550,7 @@ class Client(
         self,
         meta: dict[str, Any],
     ) -> mcp.types.InitializeResult:
-        """Initialize the MCP session while propagating MCP ``_meta`` fields.
+        """Send an InitializeRequest that preserves the client's capability config.
 
         This method accesses private session attributes (``_sampling_capabilities``,
         ``_elicitation_callback``, etc.) to reconstruct an InitializeRequest that
diff --git a/src/fastmcp/server/telemetry.py b/src/fastmcp/server/telemetry.py
index a8374d8d4..b198535a9 100644
--- a/src/fastmcp/server/telemetry.py
+++ b/src/fastmcp/server/telemetry.py
@@ -19,9 +19,9 @@ from opentelemetry.trace import (
 from fastmcp.exceptions import ToolError as _ToolError
 from fastmcp.server.http import AMBIENT_SPAN_CONTEXT_SCOPE_KEY
 from fastmcp.telemetry import (
+    extract_propagation_keys_from_meta,
     extract_trace_context,
     get_noop_span,
-    get_trace_context_carrier,
     get_tracer,
     native_telemetry_enabled,
 )
@@ -60,13 +60,13 @@ def get_session_span_attributes() -> dict[str, str]:
 
 def _get_parent_trace_context() -> tuple[Context | None, list[Link] | None]:
     """Resolve MCP server parent context plus any ambient transport links."""
-    ambient_span_context = _get_ambient_span_context()
+    ambient_span_context = _get_ambient_or_current_span_context()
 
     try:
         req_ctx = request_ctx.get()
         if req_ctx and hasattr(req_ctx, "meta") and req_ctx.meta:
             meta = dict(req_ctx.meta)
-            if get_trace_context_carrier(meta):
+            if extract_propagation_keys_from_meta(meta):
                 parent_context = extract_trace_context(meta)
                 parent_span_context = trace.get_current_span(
                     parent_context
@@ -86,8 +86,12 @@ def _get_parent_trace_context() -> tuple[Context | None, list[Link] | None]:
     return None, None
 
 
-def _get_ambient_span_context() -> SpanContext:
-    """Resolve the current ambient transport span, if one is available."""
+def _get_ambient_or_current_span_context() -> SpanContext:
+    """Resolve the ambient transport span, falling back to the current span.
+
+    Returns the span context stored in the request scope by an outer transport
+    middleware, if present and valid. Otherwise returns the current active span.
+    """
     try:
         req_ctx = request_ctx.get()
     except LookupError:
diff --git a/src/fastmcp/telemetry.py b/src/fastmcp/telemetry.py
index b8c5c22a3..ff9ac918b 100644
--- a/src/fastmcp/telemetry.py
+++ b/src/fastmcp/telemetry.py
@@ -77,7 +77,7 @@ def suppress_fastmcp_telemetry() -> Generator[None, None, None]:
         otel_context.detach(token)
 
 
-def get_trace_context_carrier(meta: dict[str, Any] | None) -> dict[str, str]:
+def extract_propagation_keys_from_meta(meta: dict[str, Any] | None) -> dict[str, str]:
     """Extract trace-related propagation keys from an MCP ``_meta`` dict."""
     if not meta:
         return {}
@@ -146,10 +146,10 @@ def extract_trace_context(meta: dict[str, Any] | None) -> Context:
 
     Returns:
         An OpenTelemetry Context with propagated trace context and baggage
-        merged onto the current context, or the current context if no
+        propagated onto the current context, or the current context if no
         propagation keys were present.
     """
-    carrier = get_trace_context_carrier(meta)
+    carrier = extract_propagation_keys_from_meta(meta)
     if carrier:
         return propagate.extract(carrier, context=otel_context.get_current())
     return otel_context.get_current()
@@ -165,9 +165,9 @@ __all__ = [
     "INSTRUMENTATION_NAME",
     "TRACE_PARENT_KEY",
     "TRACE_STATE_KEY",
+    "extract_propagation_keys_from_meta",
     "extract_trace_context",
     "get_noop_span",
-    "get_trace_context_carrier",
     "get_tracer",
     "inject_trace_context",
     "native_telemetry_enabled",