microbootstrap 1.6.0__tar.gz → 1.7.0__tar.gz

{microbootstrap-1.6.0 → microbootstrap-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: microbootstrap
-Version: 1.6.0
+Version: 1.7.0
 Summary: Package for bootstrapping new micro-services
 Keywords: python,microservice,bootstrap,opentelemetry,logging,error-tracing,litestar,fastapi,fastmcp,mcp
 Author: community-of-python
@@ -505,7 +505,7 @@ class YourSettings(BaseServiceSettings):
     opentelemetry_namespace: str | None = None
     opentelemetry_insecure: bool = True
     opentelemetry_instrumentors: list[OpenTelemetryInstrumentor] = []
-    opentelemetry_exclude_urls: list[str] = []
+    opentelemetry_exclude_urls: list[str] = ["/metrics"]
     opentelemetry_baggage_span_attributes: dict[str, str] = {}
 
     ... # Other settings here
@@ -521,9 +521,9 @@ Parameters description:
 - `opentelemetry_insecure` - is opentelemetry connection secure.
 - `opentelemetry_container_name` - will be passed to the `Resource`.
 - `opentelemetry_instrumentors` - a list of extra instrumentors.
-- `opentelemetry_exclude_urls` - list of ignored urls.
+- `opentelemetry_exclude_urls` - list of url regexes that produce no server spans (`["/metrics"]` by default). For Litestar they are combined with `OTEL_PYTHON_LITESTAR_EXCLUDED_URLS` (or `OTEL_PYTHON_EXCLUDED_URLS`), for FastMCP with `OTEL_PYTHON_STARLETTE_EXCLUDED_URLS` (or `OTEL_PYTHON_EXCLUDED_URLS`).
 - `opentelemetry_log_traces` - traces will be logged to stdout.
-- `opentelemetry_generate_health_check_spans` - generate spans for health check handlers if `True`
+- `opentelemetry_generate_health_check_spans` - generate spans for health check handlers if `True`; if `False`, `health_checks_path` is added to the excluded urls.
 - `opentelemetry_baggage_span_attributes` - maps allowed baggage keys to attributes added to local server and consumer spans.
 
 These settings are subsequently passed to [opentelemetry](https://opentelemetry.io/), finalizing your Opentelemetry integration.
@@ -559,6 +559,49 @@ class YourSettings(FastStreamSettings):
     ...
 ```
 
+#### FastMCP
+
+`FastMcpSettings` include all OpenTelemetry settings, so tracing is enabled with `opentelemetry_endpoint` alone:
+
+```python
+from fastmcp import FastMCP
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+
+from microbootstrap import FastMcpSettings
+from microbootstrap.bootstrappers.fastmcp import FastMcpBootstrapper
+from microbootstrap.instruments.opentelemetry_instrument import OpenTelemetryInstrumentor
+
+
+class YourSettings(FastMcpSettings):
+    opentelemetry_endpoint: str | None = "otel-collector:4317"
+    opentelemetry_instrumentors: list[OpenTelemetryInstrumentor] = [OpenTelemetryInstrumentor(HTTPXClientInstrumentor())]
+
+
+application: FastMCP = FastMcpBootstrapper(YourSettings()).bootstrap()
+http_application = application.http_app(path="/mcp")
+```
+
+FastMCP creates its ASGI application only when `http_app()` is called (directly or by `application.run(transport="http")`),
+so `SERVER` spans are added to every application returned by `http_app()`. Each request to it is wrapped in
+[`OpenTelemetryMiddleware`](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/asgi/asgi.html)
+and produces a span named like `POST /mcp` or `GET /health/` with the `http.route` attribute and the response status code.
+Requests to unknown paths produce spans named after the HTTP method only, without `http.route`.
+
+- `opentelemetry_endpoint` - OTLP endpoint for exported traces.
+- `opentelemetry_instrumentors` - extra instrumentors, e.g. for HTTP clients used by your tools.
+- `opentelemetry_exclude_urls` - urls without spans, `["/metrics"]` by default. Combined with `OTEL_PYTHON_STARLETTE_EXCLUDED_URLS`.
+- `opentelemetry_generate_health_check_spans` - set to `False` to skip spans for `health_checks_path`.
+- The status code attribute name depends on `OTEL_SEMCONV_STABILITY_OPT_IN`: `http.status_code` when unset,
+  `http.response.status_code` for `http`, both for `http/dup`.
+
+Applications already instrumented by `StarletteInstrumentor` are left as is, so the request is never traced twice.
+To post-process every created ASGI application yourself, use `add_http_application_postprocessor` on the bootstrapped application:
+
+```python
+application = FastMcpBootstrapper(settings).bootstrap()
+application.add_http_application_postprocessor(lambda http_application: http_application)
+```
+
 ### [Pyroscope](https://pyroscope.io)
 
 To integrate Pyroscope, specify the `pyroscope_endpoint`.

{microbootstrap-1.6.0 → microbootstrap-1.7.0}/README.md

@@ -440,7 +440,7 @@ class YourSettings(BaseServiceSettings):
     opentelemetry_namespace: str | None = None
     opentelemetry_insecure: bool = True
     opentelemetry_instrumentors: list[OpenTelemetryInstrumentor] = []
-    opentelemetry_exclude_urls: list[str] = []
+    opentelemetry_exclude_urls: list[str] = ["/metrics"]
     opentelemetry_baggage_span_attributes: dict[str, str] = {}
 
     ... # Other settings here
@@ -456,9 +456,9 @@ Parameters description:
 - `opentelemetry_insecure` - is opentelemetry connection secure.
 - `opentelemetry_container_name` - will be passed to the `Resource`.
 - `opentelemetry_instrumentors` - a list of extra instrumentors.
-- `opentelemetry_exclude_urls` - list of ignored urls.
+- `opentelemetry_exclude_urls` - list of url regexes that produce no server spans (`["/metrics"]` by default). For Litestar they are combined with `OTEL_PYTHON_LITESTAR_EXCLUDED_URLS` (or `OTEL_PYTHON_EXCLUDED_URLS`), for FastMCP with `OTEL_PYTHON_STARLETTE_EXCLUDED_URLS` (or `OTEL_PYTHON_EXCLUDED_URLS`).
 - `opentelemetry_log_traces` - traces will be logged to stdout.
-- `opentelemetry_generate_health_check_spans` - generate spans for health check handlers if `True`
+- `opentelemetry_generate_health_check_spans` - generate spans for health check handlers if `True`; if `False`, `health_checks_path` is added to the excluded urls.
 - `opentelemetry_baggage_span_attributes` - maps allowed baggage keys to attributes added to local server and consumer spans.
 
 These settings are subsequently passed to [opentelemetry](https://opentelemetry.io/), finalizing your Opentelemetry integration.
@@ -494,6 +494,49 @@ class YourSettings(FastStreamSettings):
     ...
 ```
 
+#### FastMCP
+
+`FastMcpSettings` include all OpenTelemetry settings, so tracing is enabled with `opentelemetry_endpoint` alone:
+
+```python
+from fastmcp import FastMCP
+from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
+
+from microbootstrap import FastMcpSettings
+from microbootstrap.bootstrappers.fastmcp import FastMcpBootstrapper
+from microbootstrap.instruments.opentelemetry_instrument import OpenTelemetryInstrumentor
+
+
+class YourSettings(FastMcpSettings):
+    opentelemetry_endpoint: str | None = "otel-collector:4317"
+    opentelemetry_instrumentors: list[OpenTelemetryInstrumentor] = [OpenTelemetryInstrumentor(HTTPXClientInstrumentor())]
+
+
+application: FastMCP = FastMcpBootstrapper(YourSettings()).bootstrap()
+http_application = application.http_app(path="/mcp")
+```
+
+FastMCP creates its ASGI application only when `http_app()` is called (directly or by `application.run(transport="http")`),
+so `SERVER` spans are added to every application returned by `http_app()`. Each request to it is wrapped in
+[`OpenTelemetryMiddleware`](https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/asgi/asgi.html)
+and produces a span named like `POST /mcp` or `GET /health/` with the `http.route` attribute and the response status code.
+Requests to unknown paths produce spans named after the HTTP method only, without `http.route`.
+
+- `opentelemetry_endpoint` - OTLP endpoint for exported traces.
+- `opentelemetry_instrumentors` - extra instrumentors, e.g. for HTTP clients used by your tools.
+- `opentelemetry_exclude_urls` - urls without spans, `["/metrics"]` by default. Combined with `OTEL_PYTHON_STARLETTE_EXCLUDED_URLS`.
+- `opentelemetry_generate_health_check_spans` - set to `False` to skip spans for `health_checks_path`.
+- The status code attribute name depends on `OTEL_SEMCONV_STABILITY_OPT_IN`: `http.status_code` when unset,
+  `http.response.status_code` for `http`, both for `http/dup`.
+
+Applications already instrumented by `StarletteInstrumentor` are left as is, so the request is never traced twice.
+To post-process every created ASGI application yourself, use `add_http_application_postprocessor` on the bootstrapped application:
+
+```python
+application = FastMcpBootstrapper(settings).bootstrap()
+application.add_http_application_postprocessor(lambda http_application: http_application)
+```
+
 ### [Pyroscope](https://pyroscope.io)
 
 To integrate Pyroscope, specify the `pyroscope_endpoint`.

{microbootstrap-1.6.0 → microbootstrap-1.7.0}/microbootstrap/bootstrappers/fastmcp.py

@@ -4,10 +4,15 @@ import typing
 import prometheus_client
 import typing_extensions
 from fastmcp import FastMCP
+from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
+from opentelemetry.util.http import ExcludeList, get_excluded_urls
+from starlette.applications import Starlette
 from starlette.responses import JSONResponse, Response
+from starlette.routing import Match, Mount, Route
 
 from microbootstrap.bootstrappers.base import ApplicationBootstrapper
 from microbootstrap.config.fastmcp import FastMcpConfig
+from microbootstrap.instruments import opentelemetry_instrument
 from microbootstrap.instruments.health_checks_instrument import HealthChecksInstrument, HealthCheckTypedDict
 from microbootstrap.instruments.logging_instrument import LoggingInstrument
 from microbootstrap.instruments.prometheus_instrument import FastMcpPrometheusConfig, PrometheusInstrument
@@ -18,16 +23,46 @@ from microbootstrap.settings import FastMcpSettings
 
 
 if typing.TYPE_CHECKING:
+    from fastmcp.server.http import StarletteWithLifespan
     from starlette.requests import Request
+    from starlette.types import Scope
+
+
+StarletteT = typing.TypeVar("StarletteT", bound=Starlette)
 
 
 class KwargsFastMCP(FastMCP[typing.Any]):
     def __init__(self, **kwargs: typing.Any) -> None:  # noqa: ANN401
         super().__init__(**kwargs)
+        self.http_application_postprocessors: list[typing.Callable[[StarletteWithLifespan], StarletteWithLifespan]] = []
+
+    def add_http_application_postprocessor(
+        self, postprocessor: typing.Callable[[StarletteWithLifespan], StarletteWithLifespan]
+    ) -> None:
+        self.http_application_postprocessors.append(postprocessor)
+
+    def http_app(self, *args: typing.Any, **kwargs: typing.Any) -> StarletteWithLifespan:  # noqa: ANN401
+        # ASGI application is created by the user after bootstrap, so instruments subscribe to its creation
+        http_application = super().http_app(*args, **kwargs)
+        for postprocessor in self.http_application_postprocessors:
+            http_application = postprocessor(http_application)
+        return http_application
+
+
+def build_fastmcp_route_details_from_scope(
+    scope: Scope,
+    routes: typing.Iterable[typing.Any],
+) -> tuple[str, dict[str, str]]:
+    method: typing.Final = str(scope.get("method", "HTTP")).strip()
+    for route in routes:
+        if isinstance(route, (Route, Mount)) and route.matches(scope)[0] == Match.FULL:
+            return opentelemetry_instrument.build_span_name(method, route.path), {"http.route": route.path}
+    # Unmatched paths get no `http.route` to keep its cardinality low
+    return method, {}
 
 
 class FastMcpBootstrapper(
-    ApplicationBootstrapper[FastMcpSettings, FastMCP[typing.Any], FastMcpConfig],
+    ApplicationBootstrapper[FastMcpSettings, KwargsFastMCP, FastMcpConfig],
 ):
     application_config = FastMcpConfig()
     application_type = KwargsFastMCP
@@ -41,8 +76,8 @@ class FastMcpBootstrapper(
 
     def bootstrap_before_instruments_after_app_created(
         self,
-        application: FastMCP[typing.Any],
-    ) -> FastMCP[typing.Any]:
+        application: KwargsFastMCP,
+    ) -> KwargsFastMCP:
         self.console_writer.print_bootstrap_table()
         return application
 
@@ -51,6 +86,40 @@ FastMcpBootstrapper.use_instrument()(SentryInstrument)
 FastMcpBootstrapper.use_instrument()(PyroscopeInstrument)
 
 
+@FastMcpBootstrapper.use_instrument()
+class FastMcpOpentelemetryInstrument(
+    opentelemetry_instrument.BaseOpentelemetryInstrument[opentelemetry_instrument.OpentelemetryConfig]
+):
+    def bootstrap_after(self, application: FastMCP[typing.Any]) -> FastMCP[typing.Any]:  # type: ignore[override]
+        if isinstance(application, KwargsFastMCP):
+            application.add_http_application_postprocessor(self.__instrument_http_app)
+        return application
+
+    def __instrument_http_app(self, http_application: StarletteT) -> StarletteT:
+        # `StarletteInstrumentor` marks applications the same way, so each application is instrumented once
+        if getattr(http_application, "_is_instrumented_by_opentelemetry", False):
+            return http_application
+
+        def build_route_details(scope: Scope) -> tuple[str, dict[str, str]]:
+            return build_fastmcp_route_details_from_scope(scope, http_application.routes)
+
+        http_application.add_middleware(
+            OpenTelemetryMiddleware,
+            tracer_provider=self.tracer_provider,
+            default_span_details=build_route_details,
+            excluded_urls=opentelemetry_instrument.CombinedExcludeList(
+                ExcludeList(self.define_exclude_urls()),
+                get_excluded_urls("STARLETTE"),
+            ),
+        )
+        http_application._is_instrumented_by_opentelemetry = True  # type: ignore[attr-defined]  # noqa: SLF001
+        return http_application
+
+    @classmethod
+    def get_config_type(cls) -> type[opentelemetry_instrument.OpentelemetryConfig]:
+        return opentelemetry_instrument.OpentelemetryConfig
+
+
 @FastMcpBootstrapper.use_instrument()
 class FastMcpLoggingInstrument(LoggingInstrument):
     def bootstrap_after(self, application: FastMCP[typing.Any]) -> FastMCP[typing.Any]:  # type: ignore[override]

{microbootstrap-1.6.0 → microbootstrap-1.7.0}/microbootstrap/bootstrappers/litestar.py

@@ -15,11 +15,12 @@ from litestar.openapi.plugins import SwaggerRenderPlugin
 from litestar.types.asgi_types import ASGIApp, Scope
 from litestar_offline_docs import generate_static_files_config
 from opentelemetry.instrumentation.asgi import OpenTelemetryMiddleware
-from opentelemetry.util.http import get_excluded_urls
+from opentelemetry.util.http import ExcludeList, get_excluded_urls
 from sentry_sdk.integrations.litestar import LitestarIntegration
 
 from microbootstrap.bootstrappers.base import ApplicationBootstrapper
 from microbootstrap.config.litestar import LitestarConfig
+from microbootstrap.instruments import opentelemetry_instrument
 from microbootstrap.instruments.cors_instrument import CorsInstrument
 from microbootstrap.instruments.health_checks_instrument import (
     HealthChecksInstrument,
@@ -35,7 +36,6 @@ from microbootstrap.instruments.openapi_security_schemes import (
     serialize_security_schemes,
 )
 from microbootstrap.instruments.openapi_version_docs import SUPPORTED_HTTP_METHODS
-from microbootstrap.instruments.opentelemetry_instrument import OpentelemetryInstrument
 from microbootstrap.instruments.prometheus_instrument import (
     LitestarPrometheusConfig,
     PrometheusInstrument,
@@ -239,12 +239,6 @@ class LitestarCorsInstrument(CorsInstrument):
 LitestarBootstrapper.use_instrument()(PyroscopeInstrument)
 
 
-def build_span_name(method: str, route: str) -> str:
-    if not route:
-        return method
-    return f"{method} {route}"
-
-
 def build_litestar_route_details_from_scope(
     scope: Scope,
 ) -> tuple[str, dict[str, str]]:
@@ -261,18 +255,23 @@ def build_litestar_route_details_from_scope(
     method: typing.Final = str(scope.get("method", "HTTP")).strip()
     if path_template is not None:
         path_template_stripped: typing.Final = path_template.strip()
-        return build_span_name(method, path_template_stripped), {"http.route": path_template_stripped}
+        span_name: typing.Final = opentelemetry_instrument.build_span_name(method, path_template_stripped)
+        return span_name, {"http.route": path_template_stripped}
 
     path: typing.Final = scope.get("path")
     if path is not None:
         path_stripped: typing.Final = path.strip()
-        return build_span_name(method, path_stripped), {"http.route": path_stripped}
+        return opentelemetry_instrument.build_span_name(method, path_stripped), {"http.route": path_stripped}
     return method, {}
 
 
 class LitestarOpenTelemetryInstrumentationMiddleware(ASGIMiddleware):
-    def __init__(self, config: OpenTelemetryConfig) -> None:
+    def __init__(self, config: OpenTelemetryConfig, exclude_urls: typing.Sequence[str] = ()) -> None:
         self.config = config
+        self.excluded_urls = opentelemetry_instrument.CombinedExcludeList(
+            ExcludeList(exclude_urls),
+            get_excluded_urls(self.config.exclude_urls_env_key),
+        )
 
     def create_open_telemetry_middleware(self, app: ASGIApp) -> OpenTelemetryMiddleware:
         return OpenTelemetryMiddleware(
@@ -280,7 +279,7 @@ class LitestarOpenTelemetryInstrumentationMiddleware(ASGIMiddleware):
             client_request_hook=self.config.client_request_hook_handler,
             client_response_hook=self.config.client_response_hook_handler,
             default_span_details=build_litestar_route_details_from_scope,
-            excluded_urls=get_excluded_urls(self.config.exclude_urls_env_key),
+            excluded_urls=self.excluded_urls,
             meter=self.config.meter,
             meter_provider=self.config.meter_provider,
             server_request_hook=self.config.server_request_hook_handler,
@@ -292,7 +291,7 @@ class LitestarOpenTelemetryInstrumentationMiddleware(ASGIMiddleware):
 
 
 @LitestarBootstrapper.use_instrument()
-class LitestarOpentelemetryInstrument(OpentelemetryInstrument):
+class LitestarOpentelemetryInstrument(opentelemetry_instrument.OpentelemetryInstrument):
     def bootstrap_before(self) -> dict[str, typing.Any]:
         return {
             "middleware": [
@@ -300,7 +299,8 @@ class LitestarOpentelemetryInstrument(OpentelemetryInstrument):
                     LitestarOpentelemetryConfig(
                         tracer_provider=self.tracer_provider,
                         middleware_class=LitestarOpenTelemetryInstrumentationMiddleware,  # type: ignore[arg-type]
-                    )
+                    ),
+                    exclude_urls=self.define_exclude_urls(),
                 )
             ]
         }

{microbootstrap-1.6.0 → microbootstrap-1.7.0}/microbootstrap/instruments/opentelemetry_instrument.py

@@ -19,6 +19,7 @@ from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExport
 from opentelemetry.semconv.resource import ResourceAttributes
 from opentelemetry.trace import SpanKind, format_span_id, get_current_span, set_tracer_provider
 from opentelemetry.util._importlib_metadata import entry_points
+from opentelemetry.util.http import ExcludeList
 
 from microbootstrap.instruments.base import BaseInstrumentConfig, Instrument
 from microbootstrap.instruments.sentry_instrument import snapshot_sentry_opentelemetry_baggage
@@ -70,6 +71,21 @@ def opentelemetry_baggage_scope(
         context.detach(token)
 
 
+def build_span_name(method: str, route: str) -> str:
+    if not route:
+        return method
+    return f"{method} {route}"
+
+
+class CombinedExcludeList(ExcludeList):
+    def __init__(self, *exclude_lists: ExcludeList) -> None:
+        super().__init__([])
+        self.exclude_lists = exclude_lists
+
+    def url_disabled(self, url: str) -> bool:
+        return any(one_exclude_list.url_disabled(url) for one_exclude_list in self.exclude_lists)
+
+
 @dataclasses.dataclass()
 class OpenTelemetryInstrumentor:
     instrumentor: BaseInstrumentor
@@ -167,6 +183,16 @@ class BaseOpentelemetryInstrument(Instrument[OpentelemetryConfigT]):
                 LOGGER_OBJ.debug("Instrumenting failed", entry_point_name=entry_point.name)
                 raise
 
+    def define_exclude_urls(self) -> list[str]:
+        exclude_urls: typing.Final = [*self.instrument_config.opentelemetry_exclude_urls]
+        if (
+            not self.instrument_config.opentelemetry_generate_health_check_spans
+            and self.instrument_config.health_checks_path
+            and self.instrument_config.health_checks_path not in exclude_urls
+        ):
+            exclude_urls.append(self.instrument_config.health_checks_path)
+        return exclude_urls
+
     def is_ready(self) -> bool:
         return (
             bool(self.instrument_config.opentelemetry_endpoint)
@@ -222,16 +248,6 @@ class BaseOpentelemetryInstrument(Instrument[OpentelemetryConfigT]):
 
 
 class OpentelemetryInstrument(BaseOpentelemetryInstrument[OpentelemetryConfig]):
-    def define_exclude_urls(self) -> list[str]:
-        exclude_urls: typing.Final = [*self.instrument_config.opentelemetry_exclude_urls]
-        if (
-            not self.instrument_config.opentelemetry_generate_health_check_spans
-            and self.instrument_config.health_checks_path
-            and self.instrument_config.health_checks_path not in exclude_urls
-        ):
-            exclude_urls.append(self.instrument_config.health_checks_path)
-        return exclude_urls
-
     @classmethod
     def get_config_type(cls) -> type[OpentelemetryConfig]:
         return OpentelemetryConfig

{microbootstrap-1.6.0 → microbootstrap-1.7.0}/microbootstrap/settings.py

@@ -107,6 +107,7 @@ class FastMcpSettings(  # type: ignore[misc]
     BaseServiceSettings,
     ServerConfig,
     LoggingConfig,
+    OpentelemetryConfig,
     SentryConfig,
     FastMcpPrometheusConfig,
     HealthChecksConfig,

{microbootstrap-1.6.0 → microbootstrap-1.7.0}/pyproject.toml

@@ -58,7 +58,7 @@ dependencies = [
     "opentelemetry-instrumentation-asgi>=0.46b0",
     "orjson>=3.10.18",
 ]
-version = "1.6.0"
+version = "1.7.0"
 
 [[project.authors]]
 name = "community-of-python"
@@ -90,6 +90,7 @@ dev = [
     "anyio>=4.8.0",
     "httpx>=0.28.1",
     "mypy>=1.14.1",
+    "opentelemetry-instrumentation-starlette>=0.54b1",
     "pre-commit>=4.0.1",
     "pytest>=8.3.4",
     "pytest-cov>=6.0.0",

{microbootstrap-1.6.0 → microbootstrap-1.7.0}/pyproject.toml.orig

@@ -58,7 +58,7 @@ dependencies = [
     "opentelemetry-instrumentation-asgi>=0.46b0",
     "orjson>=3.10.18",
 ]
-version = "1.6.0"
+version = "1.7.0"
 authors = [{ name = "community-of-python" }]
 
 [project.optional-dependencies]
@@ -82,6 +82,7 @@ dev = [
     "anyio>=4.8.0",
     "httpx>=0.28.1",
     "mypy>=1.14.1",
+    "opentelemetry-instrumentation-starlette>=0.54b1",
     "pre-commit>=4.0.1",
     "pytest>=8.3.4",
     "pytest-cov>=6.0.0",