aegra-api 0.1.0__py3-none-any.whl

aegra_api/observability/base.py

@@ -0,0 +1,88 @@
+"""Base observability interface for extensible tracing and monitoring."""
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ObservabilityProvider(ABC):
+    """Abstract base class for observability providers."""
+
+    @abstractmethod
+    def get_callbacks(self) -> list[Any]:
+        """Return a list of callbacks for this provider."""
+        pass
+
+    @abstractmethod
+    def get_metadata(self, run_id: str, thread_id: str, user_identity: str | None = None) -> dict[str, Any]:
+        """Return metadata to be added to the run configuration."""
+        pass
+
+    @abstractmethod
+    def is_enabled(self) -> bool:
+        """Check if this provider is enabled."""
+        pass
+
+
+class ObservabilityManager:
+    """Manages multiple observability providers."""
+
+    def __init__(self) -> None:
+        self._providers: list[ObservabilityProvider] = []
+
+    def register_provider(self, provider: ObservabilityProvider) -> None:
+        """Register an observability provider (idempotent for same instance).
+
+        Only registers enabled providers. Skips if the exact same instance
+        is already registered (checked by object identity).
+        """
+        if not provider.is_enabled():
+            return
+
+        # Check if this exact instance is already registered (by object identity)
+        if provider in self._providers:
+            return
+
+        self._providers.append(provider)
+
+    def get_all_callbacks(self) -> list[Any]:
+        """Get callbacks from all enabled providers."""
+        callbacks = []
+        for provider in self._providers:
+            try:
+                callbacks.extend(provider.get_callbacks())
+            except Exception as e:
+                logger.error(f"Failed to get callbacks from {provider.__class__.__name__}: {e}")
+        return callbacks
+
+    def get_all_metadata(self, run_id: str, thread_id: str, user_identity: str | None = None) -> dict[str, Any]:
+        """Get metadata from all enabled providers."""
+        metadata = {}
+        for provider in self._providers:
+            try:
+                provider_metadata = provider.get_metadata(run_id, thread_id, user_identity)
+                metadata.update(provider_metadata)
+            except Exception as e:
+                logger.error(f"Failed to get metadata from {provider.__class__.__name__}: {e}")
+        return metadata
+
+
+# Global observability manager instance
+_observability_manager = ObservabilityManager()
+
+
+def get_observability_manager() -> ObservabilityManager:
+    """Get the global observability manager."""
+    return _observability_manager
+
+
+def get_tracing_callbacks() -> list[Any]:
+    """Get callbacks from all registered observability providers."""
+    return _observability_manager.get_all_callbacks()
+
+
+def get_tracing_metadata(run_id: str, thread_id: str, user_identity: str | None = None) -> dict[str, Any]:
+    """Get metadata from all registered observability providers."""
+    return _observability_manager.get_all_metadata(run_id, thread_id, user_identity)

aegra_api/observability/otel.py

@@ -0,0 +1,133 @@
+"""
+Unified OpenTelemetry Provider.
+Orchestrates trace generation and fan-out export to multiple targets.
+"""
+
+import logging
+from typing import Any
+
+from openinference.instrumentation.langchain import LangChainInstrumentor
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+
+from aegra_api.observability.base import ObservabilityProvider
+from aegra_api.observability.targets import (
+    BaseOtelTarget,
+    GenericOtelTarget,
+    LangfuseTarget,
+    PhoenixTarget,
+)
+from aegra_api.settings import settings
+
+logger = logging.getLogger(__name__)
+
+
+class OpenTelemetryProvider(ObservabilityProvider):
+    """
+    Main provider that configures the global OpenTelemetry Tracer.
+    """
+
+    def __init__(self) -> None:
+        self._enabled = False
+        self._tracer_provider: TracerProvider | None = None
+
+        # Defining the list of active targets
+        self._active_targets: list[BaseOtelTarget] = self._resolve_targets()
+
+        if self._active_targets or settings.observability.OTEL_CONSOLE_EXPORT:
+            self._enabled = True
+
+    def is_enabled(self) -> bool:
+        return self._enabled
+
+    def _resolve_targets(self) -> list[BaseOtelTarget]:
+        targets: list[BaseOtelTarget] = []
+        raw_targets = settings.observability.OTEL_TARGETS
+
+        if not raw_targets:
+            return targets
+
+        for name in raw_targets.split(","):
+            name_clean = name.strip().upper()
+            if not name_clean:
+                continue
+
+            if name_clean == "LANGFUSE":
+                targets.append(LangfuseTarget())
+            elif name_clean == "PHOENIX":
+                targets.append(PhoenixTarget())
+            elif name_clean in ("GENERIC", "DEFAULT", "OTLP"):
+                targets.append(GenericOtelTarget())
+            else:
+                logger.warning(f"Unknown OTEL target in settings: {name_clean}")
+
+        return targets
+
+    def add_custom_target(self, target: BaseOtelTarget) -> None:
+        """Allow registering custom targets dynamically."""
+        self._active_targets.append(target)
+        self._enabled = True
+
+    def setup(self) -> None:
+        """Initializes the Global Tracer Provider. Runs once."""
+        if self._tracer_provider:
+            return
+
+        # 1. Resource
+        resource = Resource.create(
+            attributes={
+                "service.name": settings.observability.OTEL_SERVICE_NAME,
+                "service.version": settings.app.VERSION,
+                "deployment.environment": settings.app.ENV_MODE.lower(),
+            }
+        )
+
+        self._tracer_provider = TracerProvider(resource=resource)
+        processors_count = 0
+
+        # 2. Attach Exporters
+        for target in self._active_targets:
+            try:
+                exporter = target.get_exporter()
+                if exporter:
+                    processor = BatchSpanProcessor(exporter)
+                    self._tracer_provider.add_span_processor(processor)
+                    processors_count += 1
+                    logger.info(f"Observability: Attached target '{target.name}'")
+            except Exception as e:
+                logger.error(f"Observability: Failed to attach target '{target.name}': {e}")
+
+        # 3. Console Exporter
+        if settings.observability.OTEL_CONSOLE_EXPORT:
+            self._tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+            processors_count += 1
+            logger.info("Observability: Console export enabled")
+
+        # 4. Set Global Tracer & Instrument
+        if processors_count > 0:
+            trace.set_tracer_provider(self._tracer_provider)
+            LangChainInstrumentor().instrument(tracer_provider=self._tracer_provider)
+            logger.info("Observability: Auto-instrumentation enabled")
+
+    def get_callbacks(self) -> list[Any]:
+        if self.is_enabled():
+            self.setup()
+        return []
+
+    def get_metadata(self, run_id: str, thread_id: str, user_identity: str | None = None) -> dict[str, Any]:
+        if not self.is_enabled():
+            return {}
+
+        meta = {
+            "run_id": run_id,
+            "thread_id": thread_id,
+            "session_id": thread_id,
+        }
+        if user_identity:
+            meta["user_id"] = user_identity
+        return meta
+
+
+otel_provider = OpenTelemetryProvider()

aegra_api/observability/setup.py

@@ -0,0 +1,27 @@
+import logging
+
+from aegra_api.observability.base import get_observability_manager
+from aegra_api.observability.otel import otel_provider
+
+logger = logging.getLogger(__name__)
+
+
+def setup_observability() -> None:
+    """
+    Registers and initializes the observability subsystem.
+    Handles global OpenTelemetry setup if enabled.
+    """
+    manager = get_observability_manager()
+
+    # We are registering our single OTEL provider
+    manager.register_provider(otel_provider)
+
+    # Launching global instrumentation if the provider is active
+    if otel_provider.is_enabled():
+        try:
+            otel_provider.setup()
+            logger.info("Observability subsystem initialized successfully.")
+        except Exception as e:
+            logger.error(f"Failed to initialize observability: {e}")
+    else:
+        logger.info("Observability is disabled (no targets configured).")

aegra_api/observability/targets/__init__.py

@@ -0,0 +1,11 @@
+from aegra_api.observability.targets.base import BaseOtelTarget
+from aegra_api.observability.targets.langfuse import LangfuseTarget
+from aegra_api.observability.targets.otlp import GenericOtelTarget
+from aegra_api.observability.targets.phoenix import PhoenixTarget
+
+__all__ = [
+    "BaseOtelTarget",
+    "LangfuseTarget",
+    "PhoenixTarget",
+    "GenericOtelTarget",
+]

aegra_api/observability/targets/base.py

@@ -0,0 +1,18 @@
+from abc import ABC, abstractmethod
+
+from opentelemetry.sdk.trace.export import SpanExporter
+
+
+class BaseOtelTarget(ABC):
+    """Interface for an observability destination."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Friendly name for logging (e.g. 'Langfuse')."""
+        pass
+
+    @abstractmethod
+    def get_exporter(self) -> SpanExporter | None:
+        """Returns a configured exporter or None if config is missing."""
+        pass

aegra_api/observability/targets/langfuse.py

@@ -0,0 +1,33 @@
+import base64
+import logging
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import SpanExporter
+
+from aegra_api.observability.targets.base import BaseOtelTarget
+from aegra_api.settings import settings
+
+logger = logging.getLogger(__name__)
+
+
+class LangfuseTarget(BaseOtelTarget):
+    @property
+    def name(self) -> str:
+        return "Langfuse"
+
+    def get_exporter(self) -> SpanExporter | None:
+        conf = settings.observability
+        pk = conf.LANGFUSE_PUBLIC_KEY
+        sk = conf.LANGFUSE_SECRET_KEY
+
+        if not pk or not sk:
+            logger.debug("Langfuse credentials missing.")
+            return None
+
+        base_host = conf.LANGFUSE_BASE_URL.rstrip("/")
+        endpoint = f"{base_host}/api/public/otel/v1/traces"
+
+        auth_str = f"{pk}:{sk}"
+        auth_b64 = base64.b64encode(auth_str.encode()).decode()
+
+        return OTLPSpanExporter(endpoint=endpoint, headers={"Authorization": f"Basic {auth_b64}"})

aegra_api/observability/targets/otlp.py

@@ -0,0 +1,38 @@
+import logging
+
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import SpanExporter
+
+from aegra_api.observability.targets.base import BaseOtelTarget
+from aegra_api.settings import settings
+
+logger = logging.getLogger(__name__)
+
+
+class GenericOtelTarget(BaseOtelTarget):
+    @property
+    def name(self) -> str:
+        return "GenericOTLP"
+
+    def get_exporter(self) -> SpanExporter | None:
+        conf = settings.observability
+        if not conf.OTEL_EXPORTER_OTLP_ENDPOINT:
+            return None
+
+        return OTLPSpanExporter(
+            endpoint=conf.OTEL_EXPORTER_OTLP_ENDPOINT,
+            headers=self._parse_headers(conf.OTEL_EXPORTER_OTLP_HEADERS),
+        )
+
+    def _parse_headers(self, headers_str: str | None) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if not headers_str:
+            return headers
+        try:
+            for item in headers_str.split(","):
+                if "=" in item:
+                    k, v = item.split("=", 1)
+                    headers[k.strip()] = v.strip()
+        except Exception as e:
+            logger.warning(f"Failed to parse OTEL headers: {e}")
+        return headers

aegra_api/observability/targets/phoenix.py

@@ -0,0 +1,24 @@
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace.export import SpanExporter
+
+from aegra_api.observability.targets.base import BaseOtelTarget
+from aegra_api.settings import settings
+
+
+class PhoenixTarget(BaseOtelTarget):
+    @property
+    def name(self) -> str:
+        return "Phoenix"
+
+    def get_exporter(self) -> SpanExporter | None:
+        conf = settings.observability
+        endpoint = conf.PHOENIX_COLLECTOR_ENDPOINT
+
+        if not endpoint:
+            return None
+
+        headers = {}
+        if conf.PHOENIX_API_KEY:
+            headers["authorization"] = f"Bearer {conf.PHOENIX_API_KEY}"
+
+        return OTLPSpanExporter(endpoint=endpoint, headers=headers)