[DNM] OTEL: Instrument ctx.sample() / sampling loop

[strawgate]

Summary

• Adds OpenTelemetry tracing to the ctx.sample() / sampling loop pipeline (sample_impl, sample_step_impl, execute_tools) with sampling/createMessage, sampling/createMessage step, and sampling.execute_tool spans
• Records structured attributes (temperature, max_tokens, tool_count, result_type, iteration count, stop reason) and events for validation failures and text response retries
• Supports opt-in message content capture via OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT env var
• Adds is_recording() guards to server_span, delegate_span, and client_span to skip attribute serialization on non-recording spans
• Uses type(e).__qualname__ for error.type attribute for better nested class identification

Closes #3891

Test plan

• 9 new tests in tests/server/telemetry/test_sampling_tracing.py covering:
  • sampling/createMessage span with correct attributes and iteration count
  • sampling/createMessage step child spans per loop iteration
  • sampling.execute_tool spans for tool calls within sampling
  • Validation failure events
  • Text response retry events
• All 26 existing telemetry tests continue to pass
• ruff check src/ passes

🤖 Generated with Claude Code

[marvin-context-protocol]

Thanks for the report. This issue goes beyond what our contributor guidelines ask for — we just need a short problem description and an MRE. Please see our contributing guidelines and condense this issue. We'll triage it once it's trimmed down.

[marvin-context-protocol]

Test Failure Analysis

Summary: The static_analysis job failed because ruff format found formatting violations in src/fastmcp/server/sampling/run.py. (ty now passes — that issue from the previous triage has been resolved.)

Root Cause: ruff format reformatted src/fastmcp/server/sampling/run.py in CI, meaning the file wasn't formatted locally before committing. The violations are all in the new OTEL instrumentation code added by this PR.

Suggested Solution:

Run ruff format locally and commit the result:

uv run ruff format src/fastmcp/server/sampling/run.py

Then commit the reformatted file.

Detailed Analysis

CI output:

ruff check...   Passed
ruff format...  Failed
- hook id: ruff-format
- files were modified by this hook
ty check...     Passed

Diff applied by ruff format in CI (all in src/fastmcp/server/sampling/run.py):

1. _CAPTURE_CONTENT assignment (~line 44) — chained .lower() == "true" needs wrapping in parentheses:

# Before (fails format)
_CAPTURE_CONTENT = os.environ.get(
    "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "false"
).lower() == "true"

# After (passes format)
_CAPTURE_CONTENT = (
    os.environ.get(
        "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "false"
    ).lower()
    == "true"
)

2. set_attributes({...}) calls (~lines 296, 661) — dict literals passed directly as arguments need to be moved to their own indented block.

3. set_attribute(...) and dump_python(...) calls (~lines 691, 736, 826) — previously wrapped across multiple lines, ruff collapses them back to single lines.

Related Files

• src/fastmcp/server/sampling/run.py — new OTEL instrumentation code with ruff format violations

---

🤖 Triage by Marvin (updated to reflect latest run — ty errors resolved, ruff format still failing)