π The fast, Pythonic way to build MCP servers and clients.
fix(telemetry): record mounted and nested server spans as INTERNAL (#6252)
nate nowack15de7f090134
diff --git a/docs/servers/telemetry.mdx b/docs/servers/telemetry.mdxindex 030606899..bd5d9e544 100644--- a/docs/servers/telemetry.mdx+++ b/docs/servers/telemetry.mdx@@ -147,9 +147,11 @@ Spans form a hierarchy showing the request flow. For mounted servers:tools/call weather_forecast (CLIENT)βββ tools/call weather_forecast (SERVER, provider=FastMCPProvider)βββ delegate get_weather (INTERNAL)- βββ tools/call get_weather (SERVER, provider=LocalProvider)+ βββ tools/call get_weather (INTERNAL, provider=LocalProvider)```+Each request has exactly one `SERVER` span. The mounted server's span is `INTERNAL`, as is the span for a tool that calls another tool through `ctx.fastmcp.call_tool()`, so trace backends that count `SERVER` spans as requests count each call once.+For proxy providers connecting to remote servers:```diff --git a/fastmcp_slim/fastmcp/server/telemetry.py b/fastmcp_slim/fastmcp/server/telemetry.pyindex 4d073d45b..1226cda64 100644--- a/fastmcp_slim/fastmcp/server/telemetry.py+++ b/fastmcp_slim/fastmcp/server/telemetry.py@@ -39,6 +39,14 @@ _active_seam_span: ContextVar[Span | None] = ContextVar("fastmcp_active_seam_span", default=None)+# Set once `server_span` has claimed the request's SERVER span. A mounted+# server, or a tool calling `ctx.fastmcp.call_tool`, reaches `server_span`+# again inside that request; it records an INTERNAL span instead, so trace+# consumers see one request no matter how deep the call goes.+_server_span_open: ContextVar[bool] = ContextVar(+ "fastmcp_server_span_open", default=False+)+def get_auth_span_attributes() -> dict[str, str]:"""Get auth attributes for the current request, if authenticated."""@@ -211,12 +219,16 @@ def seam_span(method: str, server_name: str) -> Generator[Span, None, None]:if span.is_recording():restore_dropped_attributes(span, attrs)token = _active_seam_span.set(span)+ # A seam is a new inbound request, even one an in-process proxy sends+ # from inside another server's tool call.+ open_token = _server_span_open.set(False)try:yield spanexcept Exception as e:record_span_exception(span, e)raisefinally:+ _server_span_open.reset(open_token)_active_seam_span.reset(token)@@ -241,6 +253,10 @@ def server_span(e.g. in-process `mcp.call_tool()` calls that bypass the dispatcher) it opens anew SERVER span as before.+ A call nested inside that span, through a mounted server or a tool calling+ `ctx.fastmcp.call_tool`, gets an INTERNAL span under the current one, so a+ request has exactly one SERVER span.+Automatically records any exception on the span and sets error status.In `propagation_only` mode no span is opened or enriched. The seam has@@ -263,6 +279,19 @@ def server_span(prompt_name,)+ if _server_span_open.get():+ with get_tracer().start_as_current_span(+ name, kind=SpanKind.INTERNAL, attributes=attrs+ ) as span:+ if span.is_recording():+ restore_dropped_attributes(span, attrs)+ try:+ yield span+ except Exception as e:+ record_span_exception(span, e)+ raise+ return+seam = _active_seam_span.get()active = get_current_span()if (@@ -274,11 +303,14 @@ def server_span(# Enrich the already-active seam span rather than opening a second one.seam.update_name(name)seam.set_attributes(attrs)+ token = _server_span_open.set(True)try:yield seamexcept Exception as e:record_span_exception(seam, e)raise+ finally:+ _server_span_open.reset(token)returntracer = get_tracer()@@ -294,11 +326,14 @@ def server_span(# fires when the span ends up with no attributes at all.if span.is_recording():restore_dropped_attributes(span, attrs)+ token = _server_span_open.set(True)try:yield spanexcept Exception as e:record_span_exception(span, e)raise+ finally:+ _server_span_open.reset(token)@contextmanagerdiff --git a/tests/server/telemetry/test_provider_tracing.py b/tests/server/telemetry/test_provider_tracing.pyindex 50c33f8fe..f766baef7 100644--- a/tests/server/telemetry/test_provider_tracing.py+++ b/tests/server/telemetry/test_provider_tracing.py@@ -3,6 +3,7 @@from __future__ import annotationsfrom opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter+from opentelemetry.trace import SpanKindfrom fastmcp import Client, Context, FastMCPfrom fastmcp.server.providers.proxy import FastMCPProxy, ProxyClient@@ -183,3 +184,101 @@ class TestModernProxyTracePropagation:assert TRACE_PARENT_KEY in seen["resource"]assert TRACE_PARENT_KEY in seen["template"]assert TRACE_PARENT_KEY in seen["prompt"]+++class TestOneServerSpanPerRequest:+ """A request crosses one server boundary, however deep the mounts go."""++ @staticmethod+ def _server_spans(exporter: InMemorySpanExporter) -> list:+ return [+ s+ for s in exporter.get_finished_spans()+ if s.kind == SpanKind.SERVER+ and s.attributes is not None+ and s.attributes.get("mcp.method.name") == "tools/call"+ ]++ async def test_mounted_call_over_a_client(+ self, trace_exporter: InMemorySpanExporter+ ):+ child = FastMCP("child")++ @child.tool+ def hello() -> str:+ return "world"++ parent = FastMCP("parent")+ parent.mount(child, namespace="sub")++ async with Client(parent) as client:+ await client.call_tool("sub_hello", {})++ spans = trace_exporter.get_finished_spans()+ (server,) = self._server_spans(trace_exporter)+ assert server.name == "tools/call sub_hello"+ delegate = next(s for s in spans if s.name == "delegate hello")+ child_span = next(s for s in spans if s.name == "tools/call hello")+ assert child_span.kind == SpanKind.INTERNAL+ assert child_span.parent is not None+ assert child_span.parent.span_id == delegate.context.span_id++ async def test_nested_mounts_in_process(self, trace_exporter: InMemorySpanExporter):+ leaf = FastMCP("leaf")++ @leaf.tool+ def hello() -> str:+ return "world"++ middle = FastMCP("middle")+ middle.mount(leaf, namespace="leaf")+ root = FastMCP("root")+ root.mount(middle, namespace="mid")++ await root.call_tool("mid_leaf_hello", {})++ (server,) = self._server_spans(trace_exporter)+ assert server.name == "tools/call mid_leaf_hello"++ async def test_tool_calling_a_tool(self, trace_exporter: InMemorySpanExporter):+ mcp = FastMCP("nested")++ @mcp.tool+ def inner() -> str:+ return "inner"++ @mcp.tool+ async def outer(ctx: Context) -> str:+ result = await ctx.fastmcp.call_tool("inner", {})+ return str(result.structured_content)++ async with Client(mcp) as client:+ await client.call_tool("outer", {})++ (server,) = self._server_spans(trace_exporter)+ assert server.name == "tools/call outer"++ async def test_proxied_backend_keeps_its_own_server_span(+ self, trace_exporter: InMemorySpanExporter+ ):+ backend = FastMCP("backend")++ @backend.tool+ def hello() -> str:+ return "world"++ proxy = FastMCPProxy(client_factory=lambda: ProxyClient(backend))++ async with Client(proxy) as client:+ await client.call_tool("hello", {})++ names = sorted(s.name for s in self._server_spans(trace_exporter))+ assert names == ["tools/call hello", "tools/call hello"]+ backend_span = next(+ s+ for s in self._server_spans(trace_exporter)+ if s.attributes is not None+ and s.attributes.get("fastmcp.server.name") == "backend"+ )+ assert backend_span.attributes is not None+ assert backend_span.attributes.get("fastmcp.component.key") == "tool:hello@"