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
This commit is contained in:
strawgate 2026-04-25 19:11:57 -05:00
commit 9feca45fb1
3 changed files with 14 additions and 10 deletions

View file

@ -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

View file

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

View file

@ -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",