Deprecation

Author: LucasAlvesSoares

src/sap_cloud_sdk/core/telemetry/auto_instrument.py

@@ -1,5 +1,6 @@
 import logging
 import os
+import warnings
 from collections.abc import Mapping
 
 from sap_cloud_sdk.core.telemetry.middleware.base import TelemetryMiddleware
@@ -43,7 +44,10 @@ def auto_instrument(
     middlewares: list[TelemetryMiddleware] | None = None,
 ):
     """
-    Initialize meta-instrumentation for GenAI tracing. Should be initialized before any AI frameworks.
+    Initialize meta-instrumentation for GenAI tracing.
+
+    Should be called before importing your Starlette/FastAPI app so that
+    IAS JWT telemetry middleware is registered automatically.
 
     Traces are exported to the OTEL collector endpoint configured in environment with
     OTEL_EXPORTER_OTLP_ENDPOINT, or printed to console when OTEL_TRACES_EXPORTER=console.
@@ -52,13 +56,19 @@ def auto_instrument(
         disable_batch: If True, uses SimpleSpanProcessor (synchronous, lower throughput).
                        Defaults to False, which uses BatchSpanProcessor (asynchronous,
                        recommended for production workloads).
-        middlewares: Optional list of TelemetryMiddleware instances. When provided,
-                     each middleware is registered with its application and a
-                     MiddlewareSpanProcessor is added so that headers extracted by
-                     the middlewares appear as attributes on every span.
-                     Must be called before the ASGI application begins serving
-                     requests so that register() runs before the first request.
+        middlewares: Deprecated. Pass explicit TelemetryMiddleware instances.
+                     Use auto_instrument() without this parameter instead — IAS middleware
+                     is now registered automatically for supported frameworks.
+                     Will be removed in the next major version.
     """
+    if middlewares is not None:
+        warnings.warn(
+            "The middlewares= parameter of auto_instrument() is deprecated and will be "
+            "removed in the next major version. Call auto_instrument() without it — "
+            "IAS middleware is now registered automatically for supported frameworks.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
     otel_endpoint = os.getenv(ENV_OTLP_ENDPOINT, "")
     console_traces = os.getenv(ENV_TRACES_EXPORTER, "").lower() == "console"
 
@@ -161,7 +171,7 @@ def _register_middleware_processors(middlewares: list[TelemetryMiddleware]) -> N
 def _auto_instrument_frameworks(
     middlewares: list[TelemetryMiddleware] | None = None,
 ) -> None:
-    from sap_cloud_sdk.core.telemetry.middleware.registry import get_available
+    from sap_cloud_sdk.core.telemetry.middleware._registry import _get_available
     from sap_cloud_sdk.core.telemetry.middleware.span_processor import (
         MiddlewareSpanProcessor,
     )
@@ -173,29 +183,28 @@ def _auto_instrument_frameworks(
         )
         return
 
-    manual_keys = {m.framework_key for m in (middlewares or []) if m.framework_key}
+    manual_types = {type(m) for m in (middlewares or [])}
 
     instrumentors = [
-        i for i in get_available()
+        i for i in _get_available()
         if not i.__class__._processor_registered
-        and i.framework_key not in manual_keys
+        and not (i.__class__.supersedes and i.__class__.supersedes in manual_types)
     ]
 
-    if not instrumentors:
-        return
-
     skipped = [
-        i for i in get_available()
-        if i.framework_key in manual_keys
+        i for i in _get_available()
+        if i.__class__.supersedes and i.__class__.supersedes in manual_types
     ]
     for i in skipped:
         logger.warning(
-            "%s skipped: framework '%s' is already covered by an explicit middlewares= entry. "
-            "Remove the explicit middleware or do not pass it to avoid duplicate IAS span attributes.",
+            "%s skipped: an explicit middlewares= entry already covers this framework. "
+            "Remove the explicit middleware to avoid duplicate IAS span attributes.",
             type(i).__name__,
-            i.framework_key,
         )
 
+    if not instrumentors:
+        return
+
     for instr in instrumentors:
         instr.instrument()
 

src/sap_cloud_sdk/core/telemetry/middleware/__init__.py

@@ -1,20 +1,15 @@
 """HTTP framework middleware integration for Cloud SDK telemetry.
 
-Provides middleware adapters that extract request-scoped attributes
-(e.g. A2A session/task headers) and surface them as OpenTelemetry span
-attributes via auto_instrument().
+The explicit middleware path (``TelemetryMiddleware``, ``StarletteIASTelemetryMiddleware``,
+and the ``middlewares=`` parameter of ``auto_instrument()``) is deprecated and will be
+removed in the next major version. Call ``auto_instrument()`` before creating your app
+instead — IAS middleware is registered automatically.
 """
 
-from sap_cloud_sdk.core.telemetry.middleware.base import (
-    FrameworkInstrumentor,
-    TelemetryMiddleware,
-)
-from sap_cloud_sdk.core.telemetry.middleware.registry import register
+from sap_cloud_sdk.core.telemetry.middleware.base import TelemetryMiddleware
 
 __all__ = [
-    "FrameworkInstrumentor",
     "TelemetryMiddleware",
-    "register",
 ]
 
 try:
@@ -26,7 +21,8 @@
 except ImportError:
     pass
 
+# Trigger @_register side-effect for the internal Starlette instrumentor.
 try:
-    import sap_cloud_sdk.core.telemetry.middleware.starlette_instrumentor  # noqa: F401 — triggers @register
+    import sap_cloud_sdk.core.telemetry.middleware._starlette_instrumentor  # noqa: F401
 except ImportError:
     pass

src/sap_cloud_sdk/core/telemetry/middleware/_framework_instrumentor.py

@@ -0,0 +1,79 @@
+"""Internal base class for framework auto-instrumentation adapters."""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Dict, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sap_cloud_sdk.core.telemetry.middleware.base import TelemetryMiddleware
+
+logger = logging.getLogger(__name__)
+
+
+class FrameworkInstrumentor(ABC):
+    """Auto-instrumentation adapter for a specific web framework.
+
+    Internal to the SDK — not part of the public API.
+
+    Subclasses patch the framework at the class level so that any application
+    created after ``instrument()`` is called automatically gets IAS telemetry
+    middleware — no ``app=`` reference required.
+
+    The idempotency guard lives here so subclasses never need to implement it.
+    Subclasses implement ``_do_instrument`` / ``_do_uninstrument`` only.
+
+    To add support for a new framework, create a new module under
+    ``sap_cloud_sdk.core.telemetry.middleware`` (prefixed with ``_``) and
+    decorate the class with ``@_register``::
+
+        from sap_cloud_sdk.core.telemetry.middleware._registry import _register
+        from sap_cloud_sdk.core.telemetry.middleware._framework_instrumentor import FrameworkInstrumentor
+
+        @_register
+        class _DjangoIASInstrumentor(FrameworkInstrumentor):
+            @classmethod
+            def is_available(cls) -> bool:
+                try:
+                    import django  # noqa: F401
+                    return True
+                except ImportError:
+                    return False
+
+            def _do_instrument(self) -> None: ...
+            def _do_uninstrument(self) -> None: ...
+            def get_attributes(self) -> Dict[str, Any]: ...
+    """
+
+    _instrumented: bool = False
+    _processor_registered: bool = False
+    supersedes: "type[TelemetryMiddleware] | None" = None
+
+    def instrument(self) -> None:
+        if self.__class__._instrumented:
+            logger.debug("%s already instrumented, skipping", type(self).__name__)
+            return
+        self._do_instrument()
+        self.__class__._instrumented = True
+        logger.info("Instrumented %s", type(self).__name__)
+
+    def uninstrument(self) -> None:
+        if not self.__class__._instrumented:
+            return
+        self._do_uninstrument()
+        self.__class__._instrumented = False
+        self.__class__._processor_registered = False
+        logger.debug("Uninstrumented %s", type(self).__name__)
+
+    @classmethod
+    def is_available(cls) -> bool:
+        """Return True when the target framework is importable."""
+        return False
+
+    @abstractmethod
+    def _do_instrument(self) -> None: ...
+
+    @abstractmethod
+    def _do_uninstrument(self) -> None: ...
+
+    @abstractmethod
+    def get_attributes(self) -> Dict[str, Any]: ...

…dk/core/telemetry/middleware/registry.py …k/core/telemetry/middleware/_registry.pysrc/sap_cloud_sdk/core/telemetry/middleware/registry.py renamed to src/sap_cloud_sdk/core/telemetry/middleware/_registry.py src/sap_cloud_sdk/core/telemetry/middleware/registry.py renamed to src/sap_cloud_sdk/core/telemetry/middleware/_registry.py

@@ -1,37 +1,32 @@
-"""Registry for FrameworkInstrumentor subclasses.
-
-Instrumentors self-register via the ``@register`` decorator.  ``auto_instrument()``
-calls ``get_available()`` to discover and activate all installed frameworks without
-needing to know about any specific framework.
-"""
+"""Internal registry for FrameworkInstrumentor subclasses."""
 
 from __future__ import annotations
 
 import logging
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from sap_cloud_sdk.core.telemetry.middleware.base import FrameworkInstrumentor
+    from sap_cloud_sdk.core.telemetry.middleware._framework_instrumentor import FrameworkInstrumentor
 
 logger = logging.getLogger(__name__)
 
 _registry: list[type[FrameworkInstrumentor]] = []
 
 
-def register(cls: type[FrameworkInstrumentor]) -> type[FrameworkInstrumentor]:
+def _register(cls: type[FrameworkInstrumentor]) -> type[FrameworkInstrumentor]:
     """Register a FrameworkInstrumentor subclass for auto-discovery.
 
-    Use as a class decorator::
+    Internal decorator — not part of the public API::
 
-        @register
-        class StarletteIASInstrumentor(FrameworkInstrumentor):
+        @_register
+        class _StarletteIASInstrumentor(FrameworkInstrumentor):
             ...
     """
     _registry.append(cls)
     return cls
 
 
-def get_available() -> list[FrameworkInstrumentor]:
+def _get_available() -> list[FrameworkInstrumentor]:
     """Return one instance of each registered instrumentor whose framework is installed."""
     available = []
     for cls in _registry:

…try/middleware/starlette_instrumentor.py …ry/middleware/_starlette_instrumentor.pysrc/sap_cloud_sdk/core/telemetry/middleware/starlette_instrumentor.py renamed to src/sap_cloud_sdk/core/telemetry/middleware/_starlette_instrumentor.py src/sap_cloud_sdk/core/telemetry/middleware/starlette_instrumentor.py renamed to src/sap_cloud_sdk/core/telemetry/middleware/_starlette_instrumentor.py

@@ -1,4 +1,4 @@
-"""Zero-config IAS telemetry instrumentation for Starlette and FastAPI.
+"""Internal: zero-config IAS telemetry instrumentation for Starlette.
 
 Patches ``starlette.applications.Starlette`` via class substitution so that
 any app created after ``auto_instrument()`` automatically gets the IAS JWT
@@ -13,24 +13,21 @@
 from contextvars import ContextVar
 from typing import Any, Dict
 
-from sap_cloud_sdk.core.telemetry.middleware.base import FrameworkInstrumentor
-from sap_cloud_sdk.core.telemetry.middleware.registry import register
+from sap_cloud_sdk.core.telemetry.middleware._framework_instrumentor import FrameworkInstrumentor
+from sap_cloud_sdk.core.telemetry.middleware._registry import _register
+from sap_cloud_sdk.core.telemetry.middleware.starlette_a2a import (
+    StarletteIASTelemetryMiddleware,
+)
 
 logger = logging.getLogger(__name__)
 
 _attrs_var: ContextVar[Dict[str, Any]] = ContextVar("_sap_ias_attrs", default={})
 
 
-@register
-class StarletteIASInstrumentor(FrameworkInstrumentor):
-    """Instruments Starlette and FastAPI with IAS JWT telemetry middleware.
-
-    FastAPI subclasses Starlette and calls ``super().__init__()``, so patching
-    ``starlette.applications.Starlette`` covers both frameworks with one patch.
-    """
-
+@_register
+class _StarletteIASInstrumentor(FrameworkInstrumentor):
     _original: Any = None
-    framework_key = "starlette"
+    supersedes = StarletteIASTelemetryMiddleware
 
     @classmethod
     def is_available(cls) -> bool:
@@ -53,15 +50,15 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
                     self._sap_ias_done = True
                     self.add_middleware(_IASMiddleware, attrs_var=_attrs_var)
 
-        StarletteIASInstrumentor._original = original
+        _StarletteIASInstrumentor._original = original
         applications.Starlette = _SAPInstrumented
 
     def _do_uninstrument(self) -> None:
-        if StarletteIASInstrumentor._original is None:
+        if _StarletteIASInstrumentor._original is None:
             return
         from starlette import applications
-        applications.Starlette = StarletteIASInstrumentor._original
-        StarletteIASInstrumentor._original = None
+        applications.Starlette = _StarletteIASInstrumentor._original
+        _StarletteIASInstrumentor._original = None
 
     def get_attributes(self) -> Dict[str, Any]:
         return _attrs_var.get()