Add OpenTelemetry instrument for FastMCP

[personage-hub]

Motivation

FastMcpBootstrapper already wires logging, Sentry, Pyroscope, health checks and Prometheus, but has no OpenTelemetry:
FastMcpSettings does not include OpentelemetryConfig and no tracing instrument is registered. FastMCP services need the
same SERVER spans that Litestar and FastAPI already produce: http.route and the response status
code are what availability is computed from in APM. Today services work around this by mixing OpentelemetryConfig into
their settings, registering OpentelemetryInstrument by hand and calling StarletteInstrumentor().instrument_app() on the
result of http_app().

Autoloaded StarletteInstrumentor().instrument() does not help: it replaces starlette.applications.Starlette, but FastMCP
subclasses the original class at import time (StarletteWithLifespan), so apps from http_app() stay uninstrumented.

Stacked on community-of-python#151 (Honor opentelemetry_exclude_urls in the Litestar bootstrapper): reuses build_span_name, define_exclude_urls and
CombinedExcludeList moved to instruments/opentelemetry_instrument.py there. Only the last commit belongs to this PR.

Changes

• FastMcpSettings now include OpentelemetryConfig. No new required settings.
• KwargsFastMCP.http_app() calls the parent and passes the result through hooks registered with add_http_app_hook().
  The return type stays StarletteWithLifespan. This handles the case where the
  ASGI app is created after bootstrap, and it also covers run(transport="http"), which calls http_app() internally.
• FastMcpOpentelemetryInstrument adds OpenTelemetryMiddleware to every created app:
  • http.route comes from app.routes (Route/Mount, Match.FULL only). Unknown paths produce a method-only span
    with no http.route, which keeps cardinality low.
  • excluded_urls = CombinedExcludeList(ExcludeList(define_exclude_urls()), get_excluded_urls("STARLETTE")).
  • Apps that already have _is_instrumented_by_opentelemetry are skipped. The flag is set the same way
    StarletteInstrumentor sets it, so requests are never traced twice.
  • Semantic conventions are left to OpenTelemetryMiddleware (OTEL_SEMCONV_STABILITY_OPT_IN).
• FastMcpBootstrapper.bootstrap() is now typed as returning KwargsFastMCP (a FastMCP subclass), so add_http_app_hook type-checks.
• Added opentelemetry-instrumentation-starlette to the dev group so the entry-point autoload test can run.
• README: FastMCP OpenTelemetry section.

Tests

tests/bootstrappers/test_fastmcp.py:

• settings fields and tracer provider creation; instrument inactive without the relevant settings
• GET /health/ span name, http.route and status attribute for unset / http / http/dup semconv
• /metrics excluded by default; opentelemetry_exclude_urls; OTEL_PYTHON_STARLETTE_EXCLUDED_URLS; opentelemetry_generate_health_check_spans=False
• unknown path: GET span without http.route, status 404
• POST /mcp has http.route == "/mcp"
• autoloaded starlette entry point: one middleware, flag set; already-instrumented app is skipped
• opentelemetry_instrumentors (httpx) applied and torn down
• two http_app() calls produce two independently instrumented apps

just lint-ci and just test pass (238 passed).

🤖 Generated with Claude Code

[personage-hub]

Reviewed the branch locally on top of community-of-python#151: just lint clean, pytest 253 passed (26 in test_fastmcp.py). Also checked against FastMCP 3.4 from a real service: http_app() routes are plain Routes (/.well-known/oauth-protected-resource/mcp, /mcp, /health/, /metrics), the matcher resolves them exactly, /mcp/ with a trailing slash and scan paths get no route, and add_middleware after http_app() works.

The design is the right one: hooking http_app() is the only place where the ASGI app exists, the _is_instrumented_by_opentelemetry flag keeps interop with StarletteInstrumentor, exclusions combine settings and env like Litestar does after community-of-python#151, and the starlette instrumentation stays a dev-only dependency. Tests cover every case from the task, including the entry-point autoload and double http_app() calls.

Two small notes inline, neither blocks the merge. From the service side this removes the OpentelemetryConfig mixin, the manual use_instrument() and the instrument_app() call, which is exactly what we wanted.

[personage-hub]

Mount matches by prefix, so a Mount("", ...) or Mount("/", ...) (static files, a sub-app mounted at the root) would turn every unknown path into http.route="/". Cardinality stays low, so this is not a problem for the SLI, but the route then stops meaning "matched route". Worth either skipping mounts whose path is empty or /, or at least a line in the README. Not blocking.

[personage-hub]

StarletteWithLifespan is imported from fastmcp.server.http, which is not a public import path, and the extra still allows fastmcp>=2,<4. It is behind TYPE_CHECKING, so runtime is safe, but mypy users on a fastmcp version where the symbol moved would get an error from the installed package. If 2.x is still meant to be supported, a quick check that the name exists there (or typing the hook with Starlette) would settle it.