Add built-in features for OpenTelemetry 🔭 (#578)

Add built-in features for OpenTelemetry in blacksheep.server.otel namespace.

Author: RobertoPrevato

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.2] - 2025-06-??
+
+- Add built-in features to enable `OpenTelemetry` logging for all web requests
+  and exceptions, based on the examples provided in the
+  [BlackSheep-Examples](https://github.com/Neoteroi/BlackSheep-Examples/tree/main/otel)
+  repository.
+
 ## [2.3.1] - 2025-05-20 :racehorse:
 
 - Add support for [`PyPy`](https://pypy.org/), adding a pure-Python fallback

README.md

@@ -65,8 +65,8 @@ it is recommended to install `httptools`.
 
 > [!TIP]
 >
-> The best performance can be achieved using `PyPy` and
-> [`Socketify`](https://docs.socketify.dev/cli.html) (see
+> The best performance can be achieved using `PyPy` runtime, and
+> [`Socketify`](https://docs.socketify.dev/cli.html) or [`Granian`](https://github.com/emmett-framework/granian), (see
 > [#539](https://github.com/Neoteroi/BlackSheep/issues/539) for more information).
 
 ## Getting started with the documentation

blacksheep/server/otel/__init__.py

@@ -0,0 +1,247 @@
+"""
+This module provides classes and functions to enable distributed tracing and logging
+using OpenTelemetry.
+
+Additional dependencies:
+    pip install opentelemetry-distro
+    opentelemetry-bootstrap --action=install
+
+Features:
+
+- An `use_open_telemetry` function that can be used to apply useful configuration.
+- OTELMiddleware: Middleware for automatic tracing of HTTP requests.
+- Environment-based configuration for OpenTelemetry resource attributes.
+- Logging and tracing setup using user-provided exporters.
+- Context manager and decorator utilities for tracing custom operations and function
+  calls.
+
+Usage:
+    from blacksheep.server.otel import use_open_telemetry
+
+    # Configure log_exporter and span_exporter as needed
+    use_open_telemetry(app, log_exporter, span_exporter)
+"""
+
+import logging
+import os
+from contextlib import contextmanager
+from functools import wraps
+from typing import Awaitable, Callable, Dict, Optional
+
+from opentelemetry import trace
+from opentelemetry.instrumentation.logging import LoggingInstrumentor
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, LogExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter
+from opentelemetry.trace import SpanKind
+
+from blacksheep import Application
+from blacksheep.messages import Request, Response
+from blacksheep.server.env import get_env
+
+ExceptionHandler = Callable[[Request, Exception], Awaitable[Response]]
+
+
+class OTELMiddleware:
+    """
+    Middleware configuring OpenTelemetry for all web requests.
+    """
+
+    def __init__(self, exc_handler: ExceptionHandler) -> None:
+        self._exc_handler = exc_handler
+        self._tracer = trace.get_tracer(__name__)
+
+    async def __call__(self, request: Request, handler):
+        path = request.url.path.decode("utf8")
+        method = request.method
+        with self._tracer.start_as_current_span(
+            f"{method} {path}", kind=SpanKind.SERVER
+        ) as span:
+            try:
+                response = await handler(request)
+            except Exception as exc:
+                # This approach is correct because it supports controlling the response
+                # using exceptions. Unhandled exceptions are handled by the Span.
+                response = await self._exc_handler(request, exc)
+
+            self.set_span_attributes(span, request, response, path)
+            return response
+
+    def set_span_attributes(
+        self, span: trace.Span, request: Request, response: Response, path: str
+    ) -> None:
+        """
+        Configure the attributes on the span for a given request-response cycle.
+        """
+        # To reduce cardinality, update the span name to use the
+        # route that matched the request
+        route = request.route  # type: ignore
+        span.update_name(f"{request.method} {route}")
+
+        span.set_attribute("http.status_code", response.status)
+        span.set_attribute("http.method", request.method)
+        span.set_attribute("http.path", path)
+        span.set_attribute("http.url", request.url.value.decode())
+        span.set_attribute("http.route", route)
+        span.set_attribute("http.status_code", response.status)
+        span.set_attribute("client.ip", request.original_client_ip)
+
+        if response.status >= 400:
+            span.set_status(trace.Status(trace.StatusCode.ERROR))
+
+
+def _configure_logging(log_exporter: LogExporter, span_exporter: SpanExporter):
+    """
+    - Set up a custom LoggerProvider and attach a BatchLogRecordProcessor with the
+      provided log_exporter.
+    - Set the log level for the "opentelemetry" logger to WARNING to reduce noise.
+    - Add a LoggingHandler to the root logger, ensuring OpenTelemetry logs are
+      processed
+    - Instrument logging with LoggingInstrumentor().instrument(set_logging_format=True)
+      to ensure logs are formatted and correlated with traces.
+    - Set up the tracer provider and attaches a BatchSpanProcessor for the given
+      span_exporter.
+    """
+    log_provider = LoggerProvider()
+    log_provider.add_log_record_processor(BatchLogRecordProcessor(log_exporter))
+    logging.getLogger("opentelemetry").setLevel(logging.WARNING)
+    logging.getLogger().addHandler(
+        LoggingHandler(level=logging.NOTSET, logger_provider=log_provider)
+    )
+
+    LoggingInstrumentor().instrument(set_logging_format=True)
+
+    trace.set_tracer_provider(TracerProvider())
+    trace.get_tracer_provider().add_span_processor(
+        BatchSpanProcessor(span_exporter)
+    )  # type: ignore
+
+
+def set_attributes(
+    service_name: str,
+    service_namespace: str = "default",
+    env: str = "",
+):
+    """
+    Sets the OTEL_RESOURCE_ATTRIBUTES environment variable with service metadata
+    for OpenTelemetry.
+
+    Args:
+        service_name (str): The name of the service.
+        service_namespace (str, optional): The namespace of the service. Defaults to
+                                           "default".
+        env (str, optional): The deployment environment. If not provided, it is
+                            determined from the environment.
+
+    Returns:
+        None
+    """
+    if not env:
+        env = get_env()
+    os.environ["OTEL_RESOURCE_ATTRIBUTES"] = (
+        f"service.name={service_name},"
+        f"service.namespace={service_namespace},"
+        f"deployment.environment={env}"
+    )
+
+
+def use_open_telemetry(
+    app: Application,
+    log_exporter: LogExporter,
+    span_exporter: SpanExporter,
+    middleware: Optional[OTELMiddleware] = None,
+):
+    """
+    Configures OpenTelemetry tracing and logging for a BlackSheep application.
+
+    This function sets up OpenTelemetry log and span exporters, configures resource
+    attributes, and injects OTEL middleware for automatic tracing of HTTP requests.
+    It also patches the router to track matched route patterns and ensures proper
+    shutdown of the tracer provider on application stop.
+
+    Args:
+        app (Application): The BlackSheep application instance.
+        log_exporter (LogExporter): The OpenTelemetry log exporter to use.
+        span_exporter (SpanExporter): The OpenTelemetry span exporter to use.
+        middleware (optional OTELMiddleware): Custom OTEL middleware instance.
+            If not provided, the default OTELMiddleware is used.
+
+    Returns:
+        None
+    """
+    if os.getenv("OTEL_RESOURCE_ATTRIBUTES") is None:
+        # set a default value
+        set_attributes("blacksheep-app")
+
+    _configure_logging(log_exporter, span_exporter)
+
+    # Insert the middleware at the beginning of the middlewares list
+    @app.on_middlewares_configuration
+    def add_otel_middleware(app):
+        app.middlewares.insert(
+            0, middleware or OTELMiddleware(app.handle_request_handler_exception)
+        )
+
+    @app.on_start
+    async def on_start(app):
+        # Patch the router to keep track of the route pattern that matched the request,
+        # if any.
+        # https://www.neoteroi.dev/blacksheep/routing/#how-to-track-routes-that-matched-a-request
+        def wrap_get_route_match(fn):
+            @wraps(fn)
+            def get_route_match(request):
+                match = fn(request)
+                request.route = match.pattern.decode() if match else "Not Found"
+                return match
+
+            return get_route_match
+
+        app.router.get_match = wrap_get_route_match(app.router.get_match)
+
+    @app.on_stop
+    async def on_stop(app):
+        # Try calling shutdown() on app stop to flush all remaining spans.
+        try:
+            trace.get_tracer_provider().shutdown()
+        except TypeError:
+            pass
+
+
+@contextmanager
+def client_span_context(
+    operation_name: str, attributes: Dict[str, str], *args, **kwargs
+):
+    tracer = trace.get_tracer(__name__)
+    with tracer.start_as_current_span(operation_name, kind=SpanKind.CLIENT) as span:
+        span.set_attributes(attributes)
+        for i, value in enumerate(args):
+            span.set_attribute(f"@arg{i}", str(value))
+        for key, value in kwargs.items():
+            span.set_attribute(f"@{key}", str(value))
+        try:
+            yield
+        except Exception as ex:
+            span.record_exception(ex)
+            span.set_attribute("ERROR", str(ex))
+            span.set_attribute("http.status_code", 500)
+            span.set_status(trace.Status(trace.StatusCode.ERROR))
+            raise
+
+
+def logcall(component="Service"):
+    """
+    Wraps a function to log each call using OpenTelemetry, as SpanKind.CLIENT.
+    """
+
+    def log_decorator(fn):
+        @wraps(fn)
+        async def wrapper(*args, **kwargs):
+            with client_span_context(
+                fn.__name__, {"component": component}, *args, **kwargs
+            ):
+                return await fn(*args, **kwargs)
+
+        return wrapper
+
+    return log_decorator

blacksheep/server/otel/otlp.py

@@ -0,0 +1,61 @@
+"""
+This module provides integration for OpenTelemetry using OTLP (OpenTelemetry Protocol)
+exporters for logging and tracing in BlackSheep applications. This code is vendor
+agnostic as it can work with all providers supporting the OpenTelemetry Protocol
+(e.g. Grafana).
+
+It defines a helper function to configure OpenTelemetry with OTLPLogExporter and
+OTLPSpanExporter, ensuring that all required OTLP-related environment variables are set
+before initialization.
+
+Additional dependencies:
+    pip install opentelemetry-exporter-otlp
+
+Usage:
+    from blacksheep.server.otel.otlp import use_open_telemetry_otlp
+
+    use_open_telemetry_otlp(app)
+"""
+
+import os
+from typing import Optional
+
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+from blacksheep import Application
+
+from . import OTELMiddleware, use_open_telemetry
+
+__all__ = ["use_open_telemetry_otlp"]
+
+
+def use_open_telemetry_otlp(
+    app: Application, middleware: Optional[OTELMiddleware] = None
+):
+    """
+    Configures OpenTelemetry for a BlackSheep application using OTLP exporters.
+
+    This function checks for required OTLP-related environment variables and sets up
+    OpenTelemetry logging and tracing using OTLPLogExporter and OTLPSpanExporter.
+
+    Args:
+        app: The BlackSheep Application instance.
+        middleware (optional OTELMiddleware): Custom OTEL middleware instance.
+            If not provided, the default OTELMiddleware is used.
+
+    Raises:
+        ValueError: If any required OTLP environment variables are missing.
+    """
+    expected_vars = [
+        "OTEL_RESOURCE_ATTRIBUTES",
+        "OTEL_EXPORTER_OTLP_ENDPOINT",
+        "OTEL_EXPORTER_OTLP_HEADERS",
+        "OTEL_EXPORTER_OTLP_PROTOCOL",
+    ]
+    missing_vars = [var for var in expected_vars if os.environ.get(var) is None]
+    if missing_vars:
+        raise ValueError(f"Missing env variables: {', '.join(missing_vars)}")
+
+    # The following exporters use environment variables for configuration:
+    use_open_telemetry(app, OTLPLogExporter(), OTLPSpanExporter(), middleware)