π The fast, Pythonic way to build MCP servers and clients.
Expose telemetry attributes on span start (#4487)
nate nowackf018f68bbfe7
diff --git a/fastmcp_slim/fastmcp/client/telemetry.py b/fastmcp_slim/fastmcp/client/telemetry.pyindex e66cd7b47..d6a866098 100644--- a/fastmcp_slim/fastmcp/client/telemetry.py+++ b/fastmcp_slim/fastmcp/client/telemetry.py@@ -23,24 +23,25 @@ def client_span(Automatically records any exception on the span and sets error status."""+ attrs: dict[str, str] = {+ # MCP semantic conventions+ "mcp.method.name": method,+ # FastMCP-specific attributes+ "fastmcp.component.key": component_key,+ }+ if session_id is not None:+ attrs["mcp.session.id"] = session_id+ if resource_uri:+ attrs["mcp.resource.uri"] = resource_uri+ if tool_name is not None:+ attrs["gen_ai.tool.name"] = tool_name+ if prompt_name is not None:+ attrs["gen_ai.prompt.name"] = prompt_name+tracer = get_tracer()- with tracer.start_as_current_span(name, kind=SpanKind.CLIENT) as span:- if span.is_recording():- attrs: dict[str, str] = {- # MCP semantic conventions- "mcp.method.name": method,- # FastMCP-specific attributes- "fastmcp.component.key": component_key,- }- if session_id is not None:- attrs["mcp.session.id"] = session_id- if resource_uri:- attrs["mcp.resource.uri"] = resource_uri- if tool_name is not None:- attrs["gen_ai.tool.name"] = tool_name- if prompt_name is not None:- attrs["gen_ai.prompt.name"] = prompt_name- span.set_attributes(attrs)+ with tracer.start_as_current_span(+ name, kind=SpanKind.CLIENT, attributes=attrs+ ) as span:try:yield spanexcept Exception as e:diff --git a/fastmcp_slim/fastmcp/server/sampling/run.py b/fastmcp_slim/fastmcp/server/sampling/run.pyindex cb0a1e9ec..382bf8a47 100644--- a/fastmcp_slim/fastmcp/server/sampling/run.py+++ b/fastmcp_slim/fastmcp/server/sampling/run.py@@ -313,10 +313,11 @@ async def execute_tools(with tracer.start_as_current_span(f"sampling tool {tool_use.name}",kind=SpanKind.INTERNAL,+ attributes={+ "gen_ai.tool.name": tool_use.name,+ "fastmcp.tool.use_id": tool_use.id,+ },) as span:- if span.is_recording():- span.set_attribute("gen_ai.tool.name", tool_use.name)- span.set_attribute("fastmcp.tool.use_id", tool_use.id)try:result_value = await tool.run(tool_use.input)return ToolResultContent(@@ -556,12 +557,13 @@ async def sample_step_impl(with tracer.start_as_current_span("sampling create_message",kind=SpanKind.CLIENT,+ attributes={+ "mcp.method.name": "sampling/createMessage",+ "fastmcp.server.name": context.fastmcp.name,+ },record_exception=False,set_status_on_exception=False,) as span:- if span.is_recording():- span.set_attribute("mcp.method.name", "sampling/createMessage")- span.set_attribute("fastmcp.server.name", context.fastmcp.name)try:if use_fallback:response = await call_sampling_handler(diff --git a/fastmcp_slim/fastmcp/server/telemetry.py b/fastmcp_slim/fastmcp/server/telemetry.pyindex e9f6d4344..2b994b24d 100644--- a/fastmcp_slim/fastmcp/server/telemetry.py+++ b/fastmcp_slim/fastmcp/server/telemetry.py@@ -135,23 +135,21 @@ def seam_span(method: str, server_name: str) -> Generator[Span, None, None]:rejections *before* the high-level path (auth, not-found, middleware vetoes)that would otherwise produce no SERVER span at all β are recorded here."""+ attrs = {+ SEAM_SPAN_MARKER: True,+ "mcp.method.name": method,+ "fastmcp.server.name": server_name,+ **get_protocol_span_attributes(),+ **get_auth_span_attributes(),+ **get_session_span_attributes(),+ }tracer = get_tracer()with tracer.start_as_current_span(method,context=_get_parent_trace_context(),kind=SpanKind.SERVER,+ attributes=attrs,) as span:- if span.is_recording():- span.set_attribute(SEAM_SPAN_MARKER, True)- span.set_attributes(- {- "mcp.method.name": method,- "fastmcp.server.name": server_name,- **get_protocol_span_attributes(),- **get_auth_span_attributes(),- **get_session_span_attributes(),- }- )token = _active_seam_span.set(span)try:yield span@@ -218,9 +216,8 @@ def server_span(name,context=_get_parent_trace_context(),kind=SpanKind.SERVER,+ attributes=attrs,) as span:- if span.is_recording():- span.set_attributes(attrs)try:yield spanexcept Exception as e:@@ -240,16 +237,15 @@ def delegate_span(Used by FastMCPProvider when delegating to mounted servers.Automatically records any exception on the span and sets error status."""+ attrs: dict[str, str] = {+ "fastmcp.provider.type": provider_type,+ "fastmcp.component.key": component_key,+ }+ if method is not None:+ attrs["mcp.method.name"] = method+tracer = get_tracer()- with tracer.start_as_current_span(f"delegate {name}") as span:- if span.is_recording():- attrs: dict[str, str] = {- "fastmcp.provider.type": provider_type,- "fastmcp.component.key": component_key,- }- if method is not None:- attrs["mcp.method.name"] = method- span.set_attributes(attrs)+ with tracer.start_as_current_span(f"delegate {name}", attributes=attrs) as span:try:yield spanexcept Exception as e:diff --git a/tests/server/telemetry/test_sampling_tracing.py b/tests/server/telemetry/test_sampling_tracing.pyindex db02b13bc..2a550ffb3 100644--- a/tests/server/telemetry/test_sampling_tracing.py+++ b/tests/server/telemetry/test_sampling_tracing.py@@ -10,6 +10,9 @@ from __future__ import annotationsimport pytestfrom mcp_types import TextContent+from opentelemetry.context import Context as OTelContext+from opentelemetry.sdk.trace import Span, SpanProcessor, TracerProvider+from opentelemetry.sdk.trace.export import SimpleSpanProcessorfrom opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporterfrom opentelemetry.trace import StatusCode@@ -17,6 +20,28 @@ from fastmcp import Client, Context, FastMCPfrom fastmcp.client.sampling import RequestContext, SamplingMessage, SamplingParams+class OnStartRecorder(SpanProcessor):+ def __init__(self) -> None:+ self.attributes: dict[str, dict[str, object]] = {}++ def on_start(self, span: Span, parent_context: OTelContext | None = None) -> None:+ self.attributes[span.name] = dict(span.attributes or {})+++def on_start_recorder(+ monkeypatch: pytest.MonkeyPatch,+ trace_exporter: InMemorySpanExporter,+) -> OnStartRecorder:+ recorder = OnStartRecorder()+ provider = TracerProvider()+ provider.add_span_processor(recorder)+ provider.add_span_processor(SimpleSpanProcessor(trace_exporter))+ tracer = provider.get_tracer("test")+ monkeypatch.setattr("fastmcp.server.sampling.run.get_tracer", lambda: tracer)+ return recorder++def _spans_named(exporter: InMemorySpanExporter, name: str):return [s for s in exporter.get_finished_spans() if s.name == name]@@ -27,7 +52,9 @@ def _exception_events(span):class TestSamplingCreateMessageSpan:async def test_success_creates_span_with_attributes(- self, trace_exporter: InMemorySpanExporter+ self,+ trace_exporter: InMemorySpanExporter,+ on_start_recorder: OnStartRecorder,):def sampling_handler(messages: list[SamplingMessage],@@ -52,6 +79,10 @@ class TestSamplingCreateMessageSpan:assert span.attributes is not Noneassert span.attributes["mcp.method.name"] == "sampling/createMessage"assert span.attributes["fastmcp.server.name"] == "sampling-server"+ assert on_start_recorder.attributes["sampling create_message"] == {+ "mcp.method.name": "sampling/createMessage",+ "fastmcp.server.name": "sampling-server",+ }# Success path must not record any exception.assert _exception_events(span) == []assert span.status.status_code != StatusCode.ERROR@@ -93,7 +124,9 @@ class TestSamplingCreateMessageSpan:class TestSamplingToolSpan:async def test_tool_error_span_records_exception_once(- self, trace_exporter: InMemorySpanExporter+ self,+ trace_exporter: InMemorySpanExporter,+ on_start_recorder: OnStartRecorder,):from mcp_types import CreateMessageResultWithTools, ToolUseContent@@ -146,6 +179,10 @@ class TestSamplingToolSpan:assert span.status.status_code == StatusCode.ERRORassert span.attributes is not Noneassert span.attributes["gen_ai.tool.name"] == "boom_tool"+ assert on_start_recorder.attributes["sampling tool boom_tool"] == {+ "gen_ai.tool.name": "boom_tool",+ "fastmcp.tool.use_id": "call_1",+ }assert "error.type" in span.attributes# Tool spans catch-and-convert (no re-raise), so OTel auto-recording# never fires; the manual record_exception must fire exactly once.diff --git a/tests/telemetry/test_span_attributes.py b/tests/telemetry/test_span_attributes.pynew file mode 100644index 000000000..82fde174e--- /dev/null+++ b/tests/telemetry/test_span_attributes.py@@ -0,0 +1,74 @@+import pytest+from opentelemetry.context import Context+from opentelemetry.sdk.trace import Span, SpanProcessor, TracerProvider++from fastmcp.client.telemetry import client_span+from fastmcp.server.telemetry import delegate_span, seam_span, server_span+++class OnStartRecorder(SpanProcessor):+ def __init__(self) -> None:+ self.attributes: dict[str, dict[str, object]] = {}++ def on_start(self, span: Span, parent_context: Context | None = None) -> None:+ self.attributes[span.name] = dict(span.attributes or {})+++def test_known_span_attributes_are_available_on_start(+ monkeypatch: pytest.MonkeyPatch,+) -> None:+ recorder = OnStartRecorder()+ provider = TracerProvider()+ provider.add_span_processor(recorder)+ tracer = provider.get_tracer("test")+ monkeypatch.setattr("fastmcp.client.telemetry.get_tracer", lambda: tracer)+ monkeypatch.setattr("fastmcp.server.telemetry.get_tracer", lambda: tracer)++ with client_span(+ "client test",+ method="tools/call",+ component_key="tool:echo@",+ tool_name="echo",+ ):+ pass+ with server_span(+ "server test",+ method="tools/call",+ server_name="test-server",+ component_type="tool",+ component_key="tool:echo@",+ tool_name="echo",+ ):+ pass+ with seam_span("initialize test", server_name="test-server"):+ pass+ with delegate_span(+ "delegate test",+ provider_type="LocalProvider",+ component_key="tool:echo@",+ method="tools/call",+ ):+ pass++ assert recorder.attributes["client test"] == {+ "mcp.method.name": "tools/call",+ "fastmcp.component.key": "tool:echo@",+ "gen_ai.tool.name": "echo",+ }+ assert recorder.attributes["server test"] == {+ "mcp.method.name": "tools/call",+ "fastmcp.server.name": "test-server",+ "fastmcp.component.type": "tool",+ "fastmcp.component.key": "tool:echo@",+ "gen_ai.tool.name": "echo",+ }+ assert recorder.attributes["initialize test"] == {+ "fastmcp.span.seam": True,+ "mcp.method.name": "initialize test",+ "fastmcp.server.name": "test-server",+ }+ assert recorder.attributes["delegate delegate test"] == {+ "fastmcp.provider.type": "LocalProvider",+ "fastmcp.component.key": "tool:echo@",+ "mcp.method.name": "tools/call",+ }