feat(otel): move away from contrib module

docs/conf.py

@@ -117,6 +117,9 @@
     (PY_METH, "litestar.typing.ParsedType.is_subclass_of"),
     (PY_METH, "type_engine"),
     # type vars and aliases / intentionally undocumented
+    (PY_CLASS, "ClientRequestHookHandler"),
+    (PY_CLASS, "ClientResponseHookHandler"),
+    (PY_CLASS, "ServerRequestHookHandler"),
     (PY_CLASS, "AnyIOBackend"),
     (PY_CLASS, "BaseSessionBackendT"),
     (PY_CLASS, "C"),

docs/getting-started.rst

@@ -38,7 +38,7 @@ Installation
     :doc:`Prometheus Instrumentation </usage/metrics/prometheus>`
         :code:`pip install 'litestar[prometheus]'`
 
-    :doc:`Open Telemetry Instrumentation </usage/metrics/open-telemetry>`
+    :doc:`OpenTelemetry Instrumentation </usage/metrics/opentelemetry>`
         :code:`pip install 'litestar[opentelemetry]'`
 
     :doc:`SQLAlchemy </usage/databases/sqlalchemy/index>` (via `Advanced-Alchemy <https://advanced-alchemy.litestar.dev/latest/>`_)

docs/reference/contrib/index.rst

@@ -6,4 +6,3 @@ contrib
 
     jinja
     mako
-    opentelemetry

docs/reference/plugins/index.rst

@@ -12,6 +12,7 @@ plugins
     attrs
     flash_messages
     htmx
+    opentelemetry
     problem_details
     prometheus
     pydantic

docs/reference/plugins/opentelemetry.rst

@@ -0,0 +1,8 @@
+opentelemetry
+=============
+
+.. automodule:: litestar.plugins.opentelemetry
+    :members:
+
+.. automodule:: litestar.plugins.opentelemetry.config
+    :members:

docs/release-notes/changelog.rst

@@ -311,6 +311,30 @@
         and ``litestar_piccolo`` plugin instead:
         https://github.com/litestar-org/litestar-piccolo
 
+    .. change:: Move ``litestar.contrib.opentelemetry`` to ``litestar.plugins.opentelemetry`` and add upstream parity
+        :type: feature
+        :breaking:
+        :pr: 4691
+        :issue: 4466, 4468
+
+        Move the OpenTelemetry integration from ``litestar.contrib.opentelemetry`` to
+        ``litestar.plugins.opentelemetry``. Code still using imports from the old
+        module should switch to the new path.
+
+        :class:`~litestar.plugins.opentelemetry.OpenTelemetryConfig` has been brought
+        in line with the upstream
+        ``opentelemetry.instrumentation.asgi.OpenTelemetryMiddleware`` configuration,
+        adding ``client_request_hook_handler``, ``client_response_hook_handler``,
+        ``tracer``, ``exclude``, ``exclude_opt_key``, ``exclude_urls_env_key``,
+        ``exclude_spans``, ``http_capture_headers_server_request``,
+        ``http_capture_headers_server_response``, and
+        ``http_capture_headers_sanitize_fields``.
+
+        Also fixes a ``KeyError: 'route_handler'`` raised on every request when
+        ``exclude_opt_key`` was set, and corrects the ``OpenTelemetryHookHandler``
+        signature to accept the span, ASGI scope, and ASGI message as documented by
+        upstream.
+
     .. change:: Change ``Optional`` to ``NotRequired`` for pydantic fields with ``default_factory``
         :type: bugfix
         :pr: 4347

docs/usage/metrics/index.rst

@@ -4,5 +4,5 @@ Metrics
 .. toctree::
     :titlesonly:
 
-    open-telemetry
+    opentelemetry
     prometheus

docs/usage/metrics/open-telemetry.rst → docs/usage/metrics/opentelemetry.rst

@@ -1,7 +1,7 @@
 OpenTelemetry
 =============
 
-Litestar includes optional OpenTelemetry instrumentation that is exported from ``litestar.contrib.opentelemetry``. To use
+Litestar includes optional OpenTelemetry instrumentation that is exported from ``litestar.plugins.opentelemetry``. To use
 this package, you should first install the required dependencies:
 
 .. code-block:: bash
@@ -16,13 +16,13 @@ this package, you should first install the required dependencies:
     pip install 'litestar[opentelemetry]'
 
 Once these requirements are satisfied, you can instrument your Litestar application by creating an instance
-of :class:`OpenTelemetryConfig <litestar.contrib.opentelemetry.OpenTelemetryConfig>` and passing the middleware it creates to
+of :class:`OpenTelemetryConfig <litestar.plugins.opentelemetry.OpenTelemetryConfig>` and passing the middleware it creates to
 the Litestar constructor:
 
 .. code-block:: python
 
    from litestar import Litestar
-   from litestar.contrib.opentelemetry import OpenTelemetryConfig, OpenTelemetryPlugin
+   from litestar.plugins.opentelemetry import OpenTelemetryConfig, OpenTelemetryPlugin
 
    open_telemetry_config = OpenTelemetryConfig()
 
@@ -33,4 +33,4 @@ exporter to use these (see the
 `OpenTelemetry Exporter docs <https://opentelemetry.io/docs/instrumentation/python/exporters/>`_ for further details).
 
 You can also pass con figuration to the ``OpenTelemetryConfig`` telling it which providers to use. Consult
-:class:`reference docs <litestar.contrib.opentelemetry.OpenTelemetryConfig>` regarding the configuration options you can use.
+:class:`reference docs <litestar.plugins.opentelemetry.OpenTelemetryConfig>` regarding the configuration options you can use.

litestar/app.py

@@ -62,12 +62,12 @@
     from litestar.config.compression import CompressionConfig
     from litestar.config.cors import CORSConfig
     from litestar.config.csrf import CSRFConfig
-    from litestar.contrib.opentelemetry import OpenTelemetryPlugin
     from litestar.datastructures import CacheControlHeader, ETag
     from litestar.dto import AbstractDTO
     from litestar.events.listener import EventListener
     from litestar.openapi.spec import SecurityRequirement
     from litestar.openapi.spec.open_api import OpenAPI
+    from litestar.plugins.opentelemetry import OpenTelemetryPlugin
     from litestar.response import Response
     from litestar.stores.base import Store
     from litestar.types import (
@@ -493,7 +493,7 @@ def _patch_opentelemetry_middleware(config: AppConfig) -> AppConfig:
         # workaround to support otel middleware priority. Should be replaced by regular
         # middleware priorities once available
         try:
-            from litestar.contrib.opentelemetry import OpenTelemetryPlugin
+            from litestar.plugins.opentelemetry import OpenTelemetryPlugin
 
             if not any(isinstance(p, OpenTelemetryPlugin) for p in config.plugins):
                 config.middleware, otel_middleware = OpenTelemetryPlugin._pop_otel_middleware(config.middleware)

litestar/middleware/_utils.py

@@ -81,7 +81,11 @@ def should_bypass_middleware(
     if scope["type"] not in scopes:
         return True
 
-    if exclude_opt_key and scope["route_handler"].opt.get(exclude_opt_key):
+    if (
+        exclude_opt_key
+        and (route_handler := scope.get("route_handler")) is not None
+        and route_handler.opt.get(exclude_opt_key)
+    ):
         return True
 
     if exclude_http_methods and scope.get("method") in exclude_http_methods:

litestar/plugins/opentelemetry/__init__.py

@@ -0,0 +1,9 @@
+from litestar.plugins.opentelemetry.config import OpenTelemetryConfig
+from litestar.plugins.opentelemetry.middleware import OpenTelemetryInstrumentationMiddleware
+from litestar.plugins.opentelemetry.plugin import OpenTelemetryPlugin
+
+__all__ = (
+    "OpenTelemetryConfig",
+    "OpenTelemetryInstrumentationMiddleware",
+    "OpenTelemetryPlugin",
+)

litestar/contrib/opentelemetry/_utils.py → litestar/plugins/opentelemetry/_utils.py

@@ -1,5 +1,3 @@
-from __future__ import annotations
-
 from typing import TYPE_CHECKING, Any
 
 from litestar.exceptions import MissingDependencyException
@@ -12,13 +10,13 @@
 except ImportError as e:
     raise MissingDependencyException("opentelemetry") from e
 
-from opentelemetry.semconv.trace import SpanAttributes
+from opentelemetry.semconv.attributes.http_attributes import HTTP_ROUTE
 
 if TYPE_CHECKING:
     from litestar.types import Scope
 
 
-def get_route_details_from_scope(scope: Scope) -> tuple[str, dict[Any, str]]:
+def get_route_details_from_scope(scope: "Scope") -> "tuple[str, dict[Any, str]]":
     """Retrieve the span name and attributes from the ASGI scope.
 
     Args:
@@ -32,6 +30,6 @@ def get_route_details_from_scope(scope: Scope) -> tuple[str, dict[Any, str]]:
     method = str(scope.get("method", "")).strip()
 
     if method and path:  # http
-        return f"{method} {path}", {SpanAttributes.HTTP_ROUTE: f"{method} {path}"}
+        return f"{method} {path}", {HTTP_ROUTE: f"{method} {path}"}
 
-    return path, {SpanAttributes.HTTP_ROUTE: path}  # websocket
+    return path, {HTTP_ROUTE: path}  # websocket