Docs: Best practices for emitting custom spans from tools, prompts, and resources

[strawgate]

Summary

The telemetry docs show how to enable tracing and what FastMCP emits automatically, but don't guide users on how to instrument their own tool/prompt/resource implementations. Users building production MCP servers need guidance on:

Proposed content

Adding spans inside tools

from fastmcp import FastMCP
from fastmcp.telemetry import get_tracer

mcp = FastMCP("my-server")

@mcp.tool
async def search(query: str) -> str:
    tracer = get_tracer()

    with tracer.start_as_current_span("search.fetch") as span:
        span.set_attribute("search.query_length", len(query))
        results = await fetch_results(query)
        span.set_attribute("search.result_count", len(results))

    with tracer.start_as_current_span("search.rank") as span:
        ranked = rank_results(results)

    return format_results(ranked)

Recommended patterns

• Span naming: Use {tool_name}.{operation} for child spans (e.g., search.fetch, search.rank)
• What to trace: External calls (APIs, databases), expensive computations, anything >100ms
• What NOT to trace: Every function call, simple transformations, fast in-memory operations
• Attributes: Add domain-specific attributes that help debugging (counts, sizes, IDs) — not PII or secrets
• Error recording: Let exceptions propagate — FastMCP's server_span records them automatically. Don't double-record.

Instrumenting sampling calls

For servers that use ctx.sample() for LLM calls, recommend using logfire.instrument_google_genai() or equivalent to get per-LLM-call spans with token counts nested inside the tool span.

Connecting to backends

• Logfire: logfire.configure() — FastMCP spans flow automatically
• Jaeger/OTLP: opentelemetry-instrument CLI or programmatic SDK setup
• Console (debugging): ConsoleSpanExporter for raw span output

[marvin-context-protocol]

Claude finished @strawgate's task in 2m 1s —— View job

---

tl;dr

The existing "Custom Spans" section in docs/servers/telemetry.mdx (lines 154-177) is a single code snippet with no guidance. The issue proposes expanding it with naming conventions, what/when to trace, attribute hygiene, error-recording guidance (referencing the existing server_span behavior), an optional Logfire alternative, and guidance on LLM-call instrumentation. I recommend expanding the existing section in place rather than introducing a new page — all the surrounding material (SDK config, auto-instrumentation, attribute reference) is already there and provides context for the new content.

Recommendation

Expand docs/servers/telemetry.mdx §"Custom Spans" in place. Keep the scope tight:

1. What to trace / what not to trace — external I/O, expensive computations, anything >~100ms; skip trivial in-memory work.
2. Span naming — {component}.{operation} convention (e.g., search.fetch), nested under FastMCP's auto-generated tools/call {name} parent.
3. Attribute hygiene — prefer low-cardinality, domain-useful values (counts, sizes, IDs); never PII or secrets. Explicitly call out that MCP arguments frequently contain sensitive data, so don't blindly forward them.
4. Error handling — let exceptions propagate. Reference that server_span in src/fastmcp/server/telemetry.py:56 already calls record_exception + sets StatusCode.ERROR automatically, so double-recording creates noise.
5. Logfire (optional) — one short subsection showing logfire.span(...) as a terser API that still nests correctly under FastMCP spans (since both go through the same OTel tracer provider).
6. LLM-call instrumentation — point users at vendor auto-instrumentation packages (logfire.instrument_anthropic(), instrument_openai(), instrument_google_genai()) rather than hand-rolling spans around ctx.sample(). This is the highest-leverage piece for the "production MCP server" audience.

I would not add a "Connecting to backends" section — the page already covers opentelemetry-instrument CLI, programmatic TracerProvider setup, otel-desktop-viewer, and Jaeger earlier. Duplicating would be noise. A single line pointing back to the "Enabling Telemetry" / "Programmatic Configuration" sections is sufficient.

Findings

• fastmcp.telemetry.get_tracer() (src/fastmcp/telemetry.py:38) is already public and exported — the issue's proposed code works today.
• Auto-recording of exceptions on server spans is confirmed: src/fastmcp/server/telemetry.py:91-96 wraps the yield in try/except and calls span.record_exception(e) + sets error status. Guidance to "let exceptions propagate" is correct.
• The existing "Custom Spans" section already demonstrates the start_as_current_span + set_attribute pattern — the expansion should focus on the guidance layer (when, what to name, what to attribute) rather than repeating the mechanics.
• No open PR addresses this. Related open issues (Support GenAI semantic convention in open telemetry #3534 GenAI semconv, Provide the open telemetry span attributes in the start_as_current_span call #3535 span attribute kwargs, Document logging with OpenTelemetry #1998 OTEL logging, OTEL: Fix attribute compliance with MCP semantic conventions #3886 semconv compliance, OTEL: Instrument all MCP methods, not just tools/call, resources/read, prompts/get #3887 instrumenting all MCP methods, Interoperating with OpenTelemetry instrumentation in the MCP SDK #3451 MCP SDK OTEL interop) are adjacent but don't overlap — this is a standalone docs PR.

Detailed Action Plan

A junior developer can follow these steps:

1. Edit docs/servers/telemetry.mdx. Replace the current §"Custom Spans" block (lines 154-177) with an expanded version. Do not create a new .mdx file, and do not add an entry to docs.json.

2. Structure the expanded section with H3 subsections, kept brief and scannable (per CLAUDE.md: prose over code comments, motivate why before how, keep code blocks flat):

   • When to add custom spans — 3-5 line bullet list of good/bad candidates. External I/O, expensive computation, anything slow enough to matter in latency investigation. Avoid: every function call, trivial transforms, hot loops (span overhead matters).
   • Naming — one paragraph + short code snippet. {component}.{operation} form, lowercase, dot-separated. Show it nesting under the auto-generated tools/call search parent.
   • Attributes — one paragraph + short snippet. Use span.set_attribute for counts, sizes, result categories. Explicit "do not log PII, secrets, or raw tool arguments" warning (Callout/Warning component if Mintlify supports it — check other .mdx files in this dir for the idiom).
   • Errors — one paragraph. Let exceptions propagate; server_span records them automatically. Only call span.record_exception manually when you're catching+suppressing and want the trace to still reflect it.
   • Logfire — one subsection, ~10 lines prose + code. Frame as "if you're already using Logfire or want a terser API, logfire.span(...) nests correctly because both go through the OTel provider." Do not duplicate the "configure Logfire" content; link out to Logfire docs for setup.
   • Instrumenting LLM calls (best titled something like "Tracing ctx.sample() and other LLM calls") — short prose + code showing logfire.instrument_anthropic() or equivalent at startup. Note that those spans will nest under the active tool span automatically.

3. Do not duplicate backend setup. At the end of the section add a one-liner: "See Enabling Telemetry and Programmatic Configuration for exporter setup." Use in-page anchors.

4. Follow CLAUDE.md docstring/doc rules: markdown syntax (single backticks), no bare {} in JSX-interpreted positions, runnable code examples with imports, prefer named intermediate variables over deep nesting.

5. Do not edit docs/python-sdk/fastmcp-telemetry.mdx or any file under docs/python-sdk/ — per CLAUDE.md those are bot-generated.

6. Verify locally: render the docs (or at minimum eyeball the .mdx for MDX syntax issues). No tests to run for a pure docs change, but run uv run prek run --all-files before committing so Prettier normalizes the MDX.

7. PR message: 1-2 paragraphs framing the gap (docs show what FastMCP emits, not how to add your own) and the fix. Include a single focused code example. No test-plan section.

Related Items

Related issues and PRs

Repository	Issue or PR	Relevance
PrefectHQ/fastmcp	#2869 Add OpenTelemetry tracing support	Original telemetry integration.
PrefectHQ/fastmcp	#3727 [codex] Add FastMCP docs telemetry	Created the current docs/servers/telemetry.mdx this issue proposes to expand.
PrefectHQ/fastmcp	#1998 Document logging with OpenTelemetry	Adjacent — OTEL logging rather than tracing, but same docs page.
PrefectHQ/fastmcp	#3534 Support GenAI semantic convention in OTEL	Adjacent — relevant to the "instrumenting LLM calls" subsection if GenAI semconv lands before this doc change.
PrefectHQ/fastmcp	#3535 Provide span attributes in start_as_current_span	Adjacent — if merged, the code examples in the doc may use the kwargs form.
PrefectHQ/fastmcp	#3886 OTEL: Fix attribute compliance with MCP semconv	Adjacent — doesn't block this doc change.
PrefectHQ/fastmcp	#3887 OTEL: Instrument all MCP methods	Adjacent — doesn't block this doc change.
PrefectHQ/fastmcp	#3451 Interop with OpenTelemetry instrumentation in the MCP SDK	Adjacent.

Related files

File	Relevance	Sections
docs/servers/telemetry.mdx	The page to edit — existing §"Custom Spans" is a stub.	154-177
src/fastmcp/telemetry.py	get_tracer() is the public API referenced in the examples.	38-47
src/fastmcp/server/telemetry.py	server_span context manager — confirms the "don't double-record exceptions" guidance.	55-96

Related webpages

Name	URL	Relevance
OpenTelemetry Python — Manual Instrumentation	https://opentelemetry.io/docs/languages/python/instrumentation/	Canonical reference for the start_as_current_span / set_attribute APIs.
OTel semantic conventions — attribute naming	https://opentelemetry.io/docs/specs/semconv/general/attribute-naming/	Backs the "low-cardinality, dot-separated, no PII" attribute guidance.
Logfire — Manual tracing	https://logfire.pydantic.dev/docs/reference/advanced/generators/	For the Logfire subsection.
Logfire — LLM auto-instrumentation	https://logfire.pydantic.dev/docs/integrations/llms/	For the ctx.sample() / LLM instrumentation subsection.

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.