feat: Add werkzeug instrumentation and unittests

Signed-off-by: Cagri Yonca <cagri@ibm.com>

Author: CagriYonca

src/instana/__init__.py

@@ -184,6 +184,7 @@ def boot_agent() -> None:
             sqlalchemy,  # noqa: F401
             starlette,  # noqa: F401
             urllib3,  # noqa: F401
+            werkzeug,  # noqa: F401
             gevent,  # noqa: F401
         )
         from instana.instrumentation.aiohttp import (

src/instana/instrumentation/werkzeug.py

@@ -0,0 +1,354 @@
+# (c) Copyright IBM Corp. 2026
+
+"""
+Instana Werkzeug Instrumentation
+
+This module provides automatic instrumentation for Werkzeug-based applications.
+Werkzeug is a comprehensive WSGI web application library used by Flask and other frameworks.
+"""
+
+try:
+    from contextlib import contextmanager
+    from typing import (
+        TYPE_CHECKING,
+        Any,
+        Callable,
+        Dict,
+        Generator,
+        Iterable,
+        List,
+        Optional,
+        Tuple,
+    )
+
+    from opentelemetry import context, trace
+    from opentelemetry.semconv.trace import SpanAttributes
+
+    from werkzeug.wrappers import Request
+
+    from instana.log import logger
+    from instana.propagators.format import Format
+    from instana.singletons import agent, get_tracer
+    from instana.util.secrets import strip_secrets_from_query
+    from instana.util.traceutils import extract_custom_headers
+
+    if TYPE_CHECKING:
+        from instana.span.span import InstanaSpan
+
+    class InstanaWerkzeugMiddleware:
+        """
+        Instana WSGI middleware for Werkzeug applications.
+
+        This middleware automatically traces Werkzeug-based applications by:
+        - Extracting trace context from incoming requests
+        - Creating spans for each request
+        - Capturing HTTP attributes (method, path, query, headers)
+        - Injecting trace context into responses
+        - Handling errors and exceptions
+
+        Usage:
+            from werkzeug.wrappers import Request, Response
+            from instana.instrumentation.werkzeug import InstanaWerkzeugMiddleware
+
+            @Request.application
+            def application(request):
+                return Response('Hello World!')
+
+            # Wrap with Instana middleware
+            app = InstanaWerkzeugMiddleware(application)
+        """
+
+        def __init__(self, app: Callable) -> None:
+            """
+            Initialize the Instana Werkzeug middleware.
+
+            Args:
+                app: The WSGI application to wrap
+            """
+            self.app = app
+
+        def __call__(
+            self, env: Dict[str, Any], start_response: Callable
+        ) -> Iterable[bytes]:
+            """
+            WSGI application interface.
+
+            Args:
+                env: WSGI environment dictionary
+                start_response: WSGI start_response callable
+
+            Returns:
+                Iterable response body
+            """
+            try:
+                span, token = _create_span_with_context(env)
+                wrapped_start_response = _build_start_response(span, start_response)
+            except Exception as exc:
+                # Instrumentation failed - fail silently, run original app
+                logger.debug("werkzeug instrumentation setup failed", exc_info=exc)
+                return self.app(env, start_response)
+
+            try:
+                iterable = self.app(env, wrapped_start_response)
+                return _end_span_after_iterating(iterable, span, token)
+            except Exception as exc:
+                # App exception - record in span and propagate
+                try:
+                    if span and span.is_recording():
+                        span.record_exception(exc)
+                        span.end()
+                    if token:
+                        context.detach(token)
+                except Exception:
+                    logger.debug("werkzeug span cleanup failed", exc_info=True)
+                raise
+
+    def _create_span_with_context(environ: Dict[str, Any]) -> Tuple["InstanaSpan", Any]:
+        """
+        Create and configure a span with context for the request.
+
+        Args:
+            environ: WSGI environment dictionary
+
+        Returns:
+            Tuple of (span, context_token)
+        """
+        tracer = get_tracer()
+        parent_context = tracer.extract(Format.HTTP_HEADERS, environ)
+        span = tracer.start_span("wsgi", context=parent_context)
+
+        ctx = trace.set_span_in_context(span)
+        token = context.attach(ctx)
+
+        extract_custom_headers(span, environ, format=True)
+        _set_request_attributes(span, environ)
+
+        return span, token
+
+    def _build_start_response(
+        span: "InstanaSpan",
+        start_response: Callable,
+    ) -> Callable:
+        """Create an instrumented start_response callable."""
+
+        def new_start_response(
+            status: str,
+            headers: List[Tuple[str, str]],
+            exc_info: Optional[Tuple[Any, Any, Any]] = None,
+        ) -> Callable:
+            """Modified start_response with trace context injection."""
+            try:
+                extract_custom_headers(span, headers)
+                tracer = get_tracer()
+                tracer.inject(
+                    span.context,
+                    Format.HTTP_HEADERS,
+                    headers,
+                )
+
+                status_code = _parse_status_code(status)
+                if status_code is not None:
+                    if status_code >= 500:
+                        span.mark_as_errored()
+                    span.set_attribute(
+                        SpanAttributes.HTTP_STATUS_CODE,
+                        status_code,
+                    )
+
+                return start_response(
+                    status,
+                    _normalize_headers(headers),
+                    exc_info,
+                )
+            except Exception:
+                logger.debug("Error in Werkzeug start_response wrapper", exc_info=True)
+                return start_response(status, headers, exc_info)
+
+        return new_start_response
+
+    def _normalize_headers(
+        headers: List[Tuple[str, Any]],
+    ) -> List[Tuple[str, str]]:
+        """
+        Ensure all header values are strings for WSGI compliance.
+
+        Args:
+            headers: List of (name, value) tuples
+
+        Returns:
+            List of (name, str_value) tuples
+        """
+        return [
+            (name, value if isinstance(value, str) else str(value))
+            for name, value in headers
+        ]
+
+    def _parse_status_code(status: str) -> Optional[int]:
+        """Safely parse the HTTP status code from a WSGI status string."""
+        try:
+            return int(status.split()[0])
+        except (AttributeError, IndexError, TypeError, ValueError):
+            return None
+
+    def _end_span_after_iterating(
+        iterable: Iterable[bytes],
+        span: "InstanaSpan",
+        token: Any,
+    ) -> Iterable[bytes]:
+        """
+        Generator that yields from the iterable and ensures span cleanup.
+
+        Args:
+            iterable: The response iterable from the application
+            span: The active span
+            token: The context token
+
+        Yields:
+            Response chunks from the iterable
+        """
+        try:
+            yield from iterable
+        finally:
+            # Ensure iterable cleanup (important for generators)
+            if hasattr(iterable, "close"):
+                try:
+                    iterable.close()  # type: ignore
+                except Exception:
+                    logger.debug("Error closing iterable", exc_info=True)
+
+            # End span and detach token after iteration completes
+            if span and span.is_recording():
+                span.end()
+            if token:
+                context.detach(token)  # type: ignore
+
+    def _scrub_query_params(query_string: str) -> Optional[str]:
+        """
+        Scrub secrets from query string parameters.
+
+        Args:
+            query_string: The query string to scrub
+
+        Returns:
+            Scrubbed query string or None if agent not available
+        """
+        if agent is not None:
+            return strip_secrets_from_query(
+                query_string,
+                agent.options.secrets_matcher,  # type: ignore
+                agent.options.secrets_list,  # type: ignore
+            )
+        return None
+
+    def _set_request_attributes(span: "InstanaSpan", environ: Dict[str, Any]) -> None:
+        """
+        Extract and set HTTP attributes from the WSGI environ.
+
+        Args:
+            span: The active span
+            environ: WSGI environment dictionary
+        """
+        try:
+            # Set HTTP method
+            if "REQUEST_METHOD" in environ:
+                span.set_attribute(
+                    SpanAttributes.HTTP_METHOD, environ["REQUEST_METHOD"]
+                )
+
+            # Set HTTP path
+            if "PATH_INFO" in environ:
+                span.set_attribute("http.path", environ["PATH_INFO"])
+
+            # Set HTTP query parameters (with secrets scrubbed)
+            if environ.get("QUERY_STRING"):
+                scrubbed_params = _scrub_query_params(environ["QUERY_STRING"])
+                if scrubbed_params is not None:
+                    span.set_attribute("http.params", scrubbed_params)
+
+            # Set HTTP host
+            if "HTTP_HOST" in environ:
+                span.set_attribute(
+                    SpanAttributes.HTTP_HOST,
+                    environ["HTTP_HOST"],
+                )
+
+            # Set HTTP URL (without query string to avoid exposing secrets)
+            if "wsgi.url_scheme" in environ:
+                scheme = environ["wsgi.url_scheme"]
+                host = environ.get("HTTP_HOST", "")
+                script_name = environ.get("SCRIPT_NAME", "")
+                path = environ.get("PATH_INFO", "")
+
+                url = f"{scheme}://{host}{script_name}{path}"
+                span.set_attribute(SpanAttributes.HTTP_URL, url)
+
+        except Exception:
+            logger.debug("Error setting request attributes", exc_info=True)
+
+    # Context manager for manual instrumentation
+    @contextmanager
+    def trace_werkzeug_request(
+        request: Request,
+    ) -> Generator["InstanaSpan", None, None]:
+        """
+        Context manager for manually tracing Werkzeug requests.
+
+        Usage:
+            @Request.application
+            def application(request):
+                with trace_werkzeug_request(request) as span:
+                    # Your application logic
+                    span.set_attribute("custom.attribute", "value")
+                    return Response('Hello World!')
+
+        Args:
+            request: Werkzeug Request object
+
+        Yields:
+            The active span for the request
+        """
+        tracer = get_tracer()
+        span = None
+        token = None
+
+        try:
+            # Extract context from request environ (preserves multi-value headers)
+            parent_context = tracer.extract(
+                Format.HTTP_HEADERS,
+                request.environ,
+            )
+
+            # Start span
+            span = tracer.start_span("wsgi", context=parent_context)
+            ctx = trace.set_span_in_context(span)
+            token = context.attach(ctx)
+
+            # Set request attributes
+            span.set_attribute(SpanAttributes.HTTP_METHOD, request.method)
+            span.set_attribute(SpanAttributes.HTTP_URL, request.url)
+            span.set_attribute(SpanAttributes.HTTP_HOST, request.host)
+
+            if request.query_string:
+                scrubbed_params = _scrub_query_params(
+                    request.query_string.decode("utf-8")
+                )
+                if scrubbed_params is not None:
+                    span.set_attribute("http.params", scrubbed_params)
+
+            yield span
+        except Exception as exc:
+            if span and span.is_recording():
+                span.record_exception(exc)
+            raise
+        finally:
+            if span and span.is_recording():
+                span.end()
+            if token:
+                context.detach(token)
+
+    logger.debug("Instrumenting werkzeug")
+
+except ImportError:
+    pass
+
+# Made with Bob

tests/apps/werkzeug_app/__init__.py

@@ -0,0 +1 @@
+# (c) Copyright IBM Corp. 2026