fastapi-factory-utilities 0.1.0__py3-none-any.whl

fastapi_factory_utilities/core/plugins/opentelemetry_plugin/__init__.py

@@ -0,0 +1,124 @@
+"""OpenTelemetry Plugin Module."""
+
+import asyncio
+from typing import cast
+
+from opentelemetry.instrumentation.fastapi import (  # pyright: ignore[reportMissingTypeStubs]
+    FastAPIInstrumentor,
+)
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.trace import TracerProvider
+from structlog.stdlib import BoundLogger, get_logger
+
+from fastapi_factory_utilities.core.protocols import BaseApplicationProtocol
+
+from .builder import OpenTelemetryPluginBuilder
+from .configs import OpenTelemetryConfig
+from .exceptions import OpenTelemetryPluginBaseException, OpenTelemetryPluginConfigError
+
+__all__: list[str] = [
+    "OpenTelemetryConfig",
+    "OpenTelemetryPluginBaseException",
+    "OpenTelemetryPluginConfigError",
+    "OpenTelemetryPluginBuilder",
+]
+
+_logger: BoundLogger = get_logger()
+
+
+def pre_conditions_check(application: BaseApplicationProtocol) -> bool:
+    """Check the pre-conditions for the OpenTelemetry plugin.
+
+    Args:
+        application (BaseApplicationProtocol): The application.
+
+    Returns:
+        bool: True if the pre-conditions are met, False otherwise.
+    """
+    del application
+    return True
+
+
+def on_load(
+    application: BaseApplicationProtocol,
+) -> None:
+    """Actions to perform on load for the OpenTelemetry plugin.
+
+    Args:
+        application (BaseApplicationProtocol): The application.
+    """
+    # Build the OpenTelemetry Resources, TracerProvider and MeterProvider
+    try:
+        otel_builder: OpenTelemetryPluginBuilder = OpenTelemetryPluginBuilder(application=application).build_all()
+    except OpenTelemetryPluginBaseException as exception:
+        _logger.error(f"OpenTelemetry plugin failed to start. {exception}")
+        return
+    # Configuration is never None at this point (checked in the builder and raises an exception)
+    otel_config: OpenTelemetryConfig = cast(OpenTelemetryConfig, otel_builder.config)
+    # Save as state in the FastAPI application
+    application.get_asgi_app().state.tracer_provider = otel_builder.tracer_provider
+    application.get_asgi_app().state.meter_provider = otel_builder.meter_provider
+    application.get_asgi_app().state.otel_config = otel_config
+    # Instrument the FastAPI application
+    FastAPIInstrumentor.instrument_app(  # pyright: ignore[reportUnknownMemberType]
+        app=application.get_asgi_app(),
+        tracer_provider=otel_builder.tracer_provider,
+        meter_provider=otel_builder.meter_provider,
+        excluded_urls=otel_config.excluded_urls,
+    )
+
+    _logger.debug(f"OpenTelemetry plugin loaded. {otel_config.activate=}")
+
+
+async def on_startup(
+    application: BaseApplicationProtocol,
+) -> None:
+    """Actions to perform on startup for the OpenTelemetry plugin.
+
+    Args:
+        application (BaseApplicationProtocol): The application.
+
+    Returns:
+        None
+    """
+    del application
+    _logger.debug("OpenTelemetry plugin started.")
+
+
+async def on_shutdown(application: BaseApplicationProtocol) -> None:
+    """Actions to perform on shutdown for the OpenTelemetry plugin.
+
+    Args:
+        application (BaseApplicationProtocol): The application.
+
+    Returns:
+        None
+    """
+    tracer_provider: TracerProvider = application.get_asgi_app().state.tracer_provider
+    meter_provider: MeterProvider = application.get_asgi_app().state.meter_provider
+    otel_config: OpenTelemetryConfig = application.get_asgi_app().state.otel_config
+
+    seconds_to_ms_multiplier: int = 1000
+
+    async def close_tracer_provider() -> None:
+        """Close the tracer provider."""
+        tracer_provider.force_flush(timeout_millis=otel_config.closing_timeout * seconds_to_ms_multiplier)
+        # No Delay for the shutdown of the tracer provider
+        tracer_provider.shutdown()
+
+    async def close_meter_provider() -> None:
+        """Close the meter provider.
+
+        Split the timeout in half for the flush and shutdown.
+        """
+        meter_provider.force_flush(timeout_millis=int(otel_config.closing_timeout / 2) * seconds_to_ms_multiplier)
+        meter_provider.shutdown(timeout_millis=int(otel_config.closing_timeout / 2) * seconds_to_ms_multiplier)
+
+    _logger.debug("OpenTelemetry plugin stop requested. Flushing and closing...")
+
+    await asyncio.gather(
+        close_tracer_provider(),
+        close_meter_provider(),
+    )
+
+    _logger.debug("OpenTelemetry plugin closed.")

fastapi_factory_utilities/core/plugins/opentelemetry_plugin/builder.py

@@ -0,0 +1,266 @@
+"""Provides a factory function to build a objets for OpenTelemetry."""
+
+from typing import Any, Self
+
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.metrics import set_meter_provider
+from opentelemetry.propagate import set_global_textmap
+from opentelemetry.propagators.b3 import B3MultiFormat
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import MetricReader, PeriodicExportingMetricReader
+from opentelemetry.sdk.resources import (
+    DEPLOYMENT_ENVIRONMENT,
+    SERVICE_NAME,
+    SERVICE_NAMESPACE,
+    SERVICE_VERSION,
+    Resource,
+)
+from opentelemetry.sdk.trace import SynchronousMultiSpanProcessor, TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.trace import set_tracer_provider
+
+from fastapi_factory_utilities.core.plugins.opentelemetry_plugin.configs import (
+    OpenTelemetryMeterConfig,
+    OpenTelemetryTracerConfig,
+)
+from fastapi_factory_utilities.core.protocols import BaseApplicationProtocol
+from fastapi_factory_utilities.core.utils.importlib import get_path_file_in_package
+from fastapi_factory_utilities.core.utils.yaml_reader import (
+    UnableToReadYamlFileError,
+    YamlFileReader,
+)
+
+from .configs import OpenTelemetryConfig
+from .exceptions import OpenTelemetryPluginConfigError
+
+
+class OpenTelemetryPluginBuilder:
+    """Configure the injection bindings for OpenTelemetryPlugin."""
+
+    def __init__(self, application: BaseApplicationProtocol) -> None:
+        """Instantiate the OpenTelemetryPluginFactory.
+
+        Args:
+            application (BaseApplicationProtocol): The application object.
+        """
+        self._application: BaseApplicationProtocol = application
+        self._resource: Resource | None = None
+        self._config: OpenTelemetryConfig | None = None
+        self._meter_provider: MeterProvider | None = None
+        self._tracer_provider: TracerProvider | None = None
+
+    @property
+    def resource(self) -> Resource | None:
+        """Provide the resource object for OpenTelemetry.
+
+        Returns:
+            Resource | None: The resource object for OpenTelemetry.
+        """
+        return self._resource
+
+    @property
+    def config(self) -> OpenTelemetryConfig | None:
+        """Provide the configuration object for OpenTelemetry.
+
+        Returns:
+            OpenTelemetryConfig | None: The configuration object for OpenTelemetry.
+        """
+        return self._config
+
+    @property
+    def meter_provider(self) -> MeterProvider | None:
+        """Provide the meter provider object for OpenTelemetry.
+
+        Returns:
+            MeterProvider | None: The meter provider object for OpenTelemetry.
+        """
+        return self._meter_provider
+
+    @property
+    def tracer_provider(self) -> TracerProvider | None:
+        """Provide the tracer provider object for OpenTelemetry.
+
+        Returns:
+            TracerProvider | None: The tracer provider object for OpenTelemetry.
+        """
+        return self._tracer_provider
+
+    def build_resource(self) -> Self:
+        """Build a resource object for OpenTelemetry from the application and configs.
+
+        Returns:
+            Self: The OpenTelemetryPluginFactory object.
+        """
+        self._resource = Resource(
+            attributes={
+                DEPLOYMENT_ENVIRONMENT: self._application.get_config().environment.value,
+                SERVICE_NAME: self._application.get_config().service_name,
+                SERVICE_NAMESPACE: self._application.get_config().service_namespace,
+                SERVICE_VERSION: self._application.get_config().version,
+            }
+        )
+        return self
+
+    def build_config(
+        self,
+    ) -> Self:
+        """Build the configuration object for OpenTelemetry from the application.
+
+        Returns:
+            Self: The OpenTelemetryPluginFactory object.
+
+        Raises:
+            OpenTelemetryPluginConfigError: If the package name is not set in the application.
+            OpenTelemetryPluginConfigError: If the application configuration file is not found.
+
+        """
+        if self._application.PACKAGE_NAME == "":
+            raise OpenTelemetryPluginConfigError("The package name must be set in the concrete application class.")
+
+        # Read the application configuration file
+        try:
+            yaml_file_content: dict[str, Any] = YamlFileReader(
+                file_path=get_path_file_in_package(
+                    filename="application.yaml",
+                    package=self._application.PACKAGE_NAME,
+                ),
+                yaml_base_key="opentelemetry",
+                use_environment_injection=True,
+            ).read()
+        except (FileNotFoundError, ImportError, UnableToReadYamlFileError) as exception:
+            raise OpenTelemetryPluginConfigError("Unable to read the application configuration file.") from exception
+
+        # Create the application configuration model
+        try:
+            self._config = OpenTelemetryConfig(**yaml_file_content)
+        except ValueError as exception:
+            raise OpenTelemetryPluginConfigError("Unable to create the application configuration model.") from exception
+
+        return self
+
+    def build_meter_provider(
+        self,
+    ) -> Self:
+        """Build a meter provider object for OpenTelemetry.
+
+        Returns:
+            Self: The OpenTelemetryPluginFactory object.
+        """
+        if self._resource is None:
+            raise OpenTelemetryPluginConfigError("The resource object is missing.")
+
+        if self._config is None:
+            raise OpenTelemetryPluginConfigError("The configuration object is missing.")
+
+        readers: list[MetricReader] = []
+        if self._config.activate is True:
+            if self._config.meter_config is None:
+                # TODO: switch to a custom exception
+                raise OpenTelemetryPluginConfigError("The meter configuration is missing.")
+
+            # TODO: Extract to a dedicated method for the exporter and period reader setup
+
+            # Setup the Exporter
+            exporter = OTLPMetricExporter(
+                endpoint=f"{self._config.endpoint.unicode_string()}v1/metrics",
+                timeout=self._config.timeout,
+            )
+
+            # Setup the Metric Reader
+            meter_config: OpenTelemetryMeterConfig = self._config.meter_config
+            reader = PeriodicExportingMetricReader(
+                exporter=exporter,
+                export_interval_millis=meter_config.reader_interval_millis,
+                export_timeout_millis=meter_config.reader_timeout_millis,
+            )
+            readers.append(reader)
+
+        # Setup the Meter Provider
+        self._meter_provider = MeterProvider(
+            resource=self._resource,
+            metric_readers=readers,
+            shutdown_on_exit=True,
+            views=[],
+        )
+
+        set_meter_provider(self._meter_provider)
+
+        return self
+
+    def build_tracer_provider(
+        self,
+    ) -> Self:
+        """Provides a tracer provider for OpenTelemetry.
+
+        Returns:
+            Self: The OpenTelemetryPluginFactory object.
+
+        Raises:
+            OpenTelemetryPluginConfigError: If the resource object is missing.
+            OpenTelemetryPluginConfigError: If the configuration object is missing.
+        """
+        if self._resource is None:
+            raise OpenTelemetryPluginConfigError("The resource object is missing.")
+
+        if self._config is None:
+            raise OpenTelemetryPluginConfigError("The configuration object is missing.")
+
+        active_span_processor: SynchronousMultiSpanProcessor | None = None
+
+        # Exit with a void TracerProvider if the export is not activated
+        if self._config.activate is True:
+            if self._config.tracer_config is None:
+                raise OpenTelemetryPluginConfigError("The tracer configuration is missing.")
+
+            # Setup the Exporter
+            exporter = OTLPSpanExporter(
+                endpoint=f"{self._config.endpoint.unicode_string()}v1/traces",
+                timeout=self._config.timeout,
+            )
+
+            # Setup the Span Processor
+            tracer_config: OpenTelemetryTracerConfig = self._config.tracer_config
+            span_processor = BatchSpanProcessor(
+                span_exporter=exporter,
+                max_queue_size=tracer_config.max_queue_size,
+                max_export_batch_size=tracer_config.max_export_batch_size,
+                schedule_delay_millis=tracer_config.schedule_delay_millis,
+                export_timeout_millis=tracer_config.export_timeout_millis,
+            )
+
+            # Setup the Multi Span Processor
+            active_span_processor = SynchronousMultiSpanProcessor()
+            active_span_processor.add_span_processor(span_processor=span_processor)
+
+            # Setup the TextMap Propagator for B3
+            set_global_textmap(http_text_format=B3MultiFormat())
+
+        # Setup the Tracer Provider
+        self._tracer_provider = TracerProvider(
+            sampler=None,
+            resource=self._resource,
+            active_span_processor=active_span_processor,
+            id_generator=None,
+            span_limits=None,
+            shutdown_on_exit=True,
+        )
+
+        set_tracer_provider(self._tracer_provider)
+
+        return self
+
+    def build_all(
+        self,
+    ) -> Self:
+        """Build all the objects for OpenTelemetry.
+
+        Returns:
+            Self: The OpenTelemetryPluginFactory object.
+        """
+        self.build_resource()
+        self.build_config()
+        self.build_meter_provider()
+        self.build_tracer_provider()
+
+        return self

fastapi_factory_utilities/core/plugins/opentelemetry_plugin/configs.py

@@ -0,0 +1,103 @@
+"""Provides the configuration model for the OpenTelemetry plugin."""
+
+from typing import Annotated
+
+from pydantic import BaseModel, ConfigDict, Field, UrlConstraints
+from pydantic_core import Url
+
+
+class OpenTelemetryMeterConfig(BaseModel):
+    """Provides the configuration model for the OpenTelemetry meter as sub-model."""
+
+    # Constants for time in milliseconds and seconds
+    ONE_MINUTE_IN_MILLIS: int = 60000
+    ONE_SECOND_IN_MILLIS: int = 1000
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    reader_interval_millis: float = Field(
+        default=ONE_SECOND_IN_MILLIS,
+        description="The interval in miliseconds to read and export metrics.",
+    )
+
+    reader_timeout_millis: float = Field(
+        default=ONE_SECOND_IN_MILLIS,
+        description="The timeout in miliseconds for the reader.",
+    )
+
+
+class OpenTelemetryTracerConfig(BaseModel):
+    """Provides the configuration model for the OpenTelemetry tracer as sub-model."""
+
+    # Constants for time in milliseconds and seconds
+    FIVE_SECONDS_IN_MILLIS: int = 5000
+    THIRTY_SECONDS_IN_MILLIS: int = 30000
+
+    # Default values for the OpenTelemetry tracer
+    DEFAULT_OTEL_TRACER_MAX_QUEUE_SIZE: int = 2048
+    DEFAULT_OTEL_TRACER_MAX_EXPORT_BATCH_SIZE: int = 512
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    max_queue_size: int = Field(
+        default=DEFAULT_OTEL_TRACER_MAX_QUEUE_SIZE,
+        description="The maximum queue size for the tracer.",
+    )
+    max_export_batch_size: int = Field(
+        default=DEFAULT_OTEL_TRACER_MAX_EXPORT_BATCH_SIZE,
+        description="The maximum export batch size for the tracer.",
+    )
+    schedule_delay_millis: int = Field(
+        default=FIVE_SECONDS_IN_MILLIS,
+        description="The schedule delay in miliseconds for the tracer.",
+    )
+    export_timeout_millis: int = Field(
+        default=THIRTY_SECONDS_IN_MILLIS,
+        description="The export timeout in miliseconds for the tracer.",
+    )
+
+
+class OpenTelemetryConfig(BaseModel):
+    """Provides the configuration model for the OpenTelemetry plugin."""
+
+    # Constants for time in milliseconds and seconds
+    TEN_SECONDS_IN_SECONDS: int = 10
+
+    # Default value for the collector endpoint
+    DEFAULT_COLLECTOR_ENDPOINT: str = "http://localhost:4318"
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    activate: bool = Field(
+        default=False,
+        description="Whether to activate the OpenTelemetry collector export.",
+    )
+    endpoint: Annotated[Url, UrlConstraints(allowed_schemes=["http", "https"])] = Field(
+        default=Url(url=DEFAULT_COLLECTOR_ENDPOINT),
+        description="The collector endpoint.",
+    )
+
+    timeout: int = Field(
+        default=TEN_SECONDS_IN_SECONDS,
+        description="The timeout in seconds for the collector.",
+    )
+
+    closing_timeout: int = Field(
+        default=TEN_SECONDS_IN_SECONDS,
+        description="The closing timeout in seconds for the collector.",
+    )
+
+    meter_config: OpenTelemetryMeterConfig | None = Field(
+        default_factory=OpenTelemetryMeterConfig,
+        description="The meter configuration.",
+    )
+
+    tracer_config: OpenTelemetryTracerConfig | None = Field(
+        default_factory=OpenTelemetryTracerConfig,
+        description="The tracer configuration.",
+    )
+
+    excluded_urls: list[str] = Field(
+        default_factory=list,
+        description="The excluded URLs for both the metrics and traces.",
+    )

fastapi_factory_utilities/core/plugins/opentelemetry_plugin/exceptions.py

@@ -0,0 +1,13 @@
+"""Provides the exceptions for the OpenTelemetryPlugin."""
+
+
+class OpenTelemetryPluginBaseException(BaseException):
+    """Base exception for the OpenTelemetryPlugin."""
+
+    pass
+
+
+class OpenTelemetryPluginConfigError(OpenTelemetryPluginBaseException):
+    """Exception for the OpenTelemetryPlugin configuration."""
+
+    pass

fastapi_factory_utilities/core/plugins/opentelemetry_plugin/helpers.py

@@ -0,0 +1,42 @@
+"""Provides helper functions for the OpenTelemetry plugin."""
+
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+from opentelemetry import trace
+from opentelemetry.context import Context
+from opentelemetry.trace import SpanKind
+from opentelemetry.util import types
+
+Param = ParamSpec("Param")
+RetType = TypeVar("RetType")  # pylint: disable=invalid-name
+
+
+def trace_span(
+    name: str | None = None,
+    context: Context | None = None,
+    kind: SpanKind = SpanKind.INTERNAL,
+    attributes: types.Attributes = None,
+) -> Callable[[Callable[Param, RetType]], Callable[Param, RetType]]:
+    """Decorator to trace a function using OpenTelemetry."""
+
+    def decorator(func: Callable[Param, RetType]) -> Callable[Param, RetType]:
+        @wraps(wrapped=func)
+        def wrapper(*args: Param.args, **kwargs: Param.kwargs) -> RetType:
+            # Get Tracer from the instrumented function's module
+            tracer: trace.Tracer = trace.get_tracer(instrumenting_module_name=func.__module__)
+            # Use the function's name as the span name if no name is provided
+            trace_name: str = name if name is not None else func.__name__
+            # Start a span with the provided name
+            with tracer.start_as_current_span(
+                name=trace_name,
+                kind=kind,
+                context=context,
+                attributes=attributes,
+            ):
+                return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

fastapi_factory_utilities/core/protocols.py

@@ -0,0 +1,82 @@
+"""Protocols for the base application."""
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, ClassVar, Protocol, runtime_checkable
+
+from beanie import Document
+from fastapi import FastAPI
+
+if TYPE_CHECKING:
+    from fastapi_factory_utilities.core.app.base.config_abstract import (
+        AppConfigAbstract,
+    )
+
+
+class BaseApplicationProtocol(Protocol):
+    """Protocol for the base application."""
+
+    PACKAGE_NAME: str
+
+    ODM_DOCUMENT_MODELS: ClassVar[list[type[Document]]]
+
+    @abstractmethod
+    def get_config(self) -> "AppConfigAbstract":
+        """Get the application configuration."""
+
+    @abstractmethod
+    def get_asgi_app(self) -> FastAPI:
+        """Get the ASGI application."""
+
+
+@runtime_checkable
+class PluginProtocol(Protocol):
+    """Defines the protocol for the plugin.
+
+    Attributes:
+        INJECTOR_MODULE (type[Module]): The module for the plugin.
+
+    """
+
+    @abstractmethod
+    def pre_conditions_check(self, application: BaseApplicationProtocol) -> bool:
+        """Check the pre-conditions for the plugin.
+
+        Args:
+            application (BaseApplicationProtocol): The application.
+
+        Returns:
+            bool: True if the pre-conditions are met, False otherwise.
+        """
+
+    @abstractmethod
+    def on_load(self, application: BaseApplicationProtocol) -> None:
+        """The actions to perform on load for the plugin.
+
+        Args:
+            application (BaseApplicationProtocol): The application.
+
+        Returns:
+            None
+        """
+
+    @abstractmethod
+    async def on_startup(self, application: BaseApplicationProtocol) -> None:
+        """The actions to perform on startup for the plugin.
+
+        Args:
+            application (BaseApplicationProtocol): The application.
+
+        Returns:
+            None
+        """
+
+    @abstractmethod
+    async def on_shutdown(self, application: BaseApplicationProtocol) -> None:
+        """The actions to perform on shutdown for the plugin.
+
+        Args:
+            application (BaseApplicationProtocol): The application.
+
+        Returns:
+            None
+        """