fraiseql-confiture 0.3.4__cp311-cp311-win_amd64.whl

confiture/core/observability/metrics.py

@@ -0,0 +1,174 @@
+"""Prometheus metrics for migrations.
+
+Provides optional metrics integration for migration monitoring.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MetricsConfig:
+    """Configuration for Prometheus metrics."""
+
+    enabled: bool = False
+    port: int = 9090
+    path: str = "/metrics"
+
+
+class MigrationMetrics:
+    """Prometheus metrics for migrations.
+
+    Exposes metrics when prometheus_client is installed:
+    - confiture_migrations_total (counter)
+    - confiture_migration_duration_seconds (histogram)
+    - confiture_migration_errors_total (counter)
+    - confiture_migration_last_success_timestamp (gauge)
+
+    Example:
+        >>> metrics = MigrationMetrics(MetricsConfig(enabled=True))
+        >>> metrics.start_server()
+        >>> metrics.record_migration("001", "create_users", 2.5, success=True)
+    """
+
+    def __init__(self, config: MetricsConfig):
+        """Initialize migration metrics.
+
+        Args:
+            config: Metrics configuration
+        """
+        self.config = config
+        self._registry: Any = None
+        self._migrations_total: Any = None
+        self._migration_duration: Any = None
+        self._migration_errors: Any = None
+        self._last_success: Any = None
+        self._initialized = False
+
+        if config.enabled:
+            self._initialize_metrics()
+
+    def _initialize_metrics(self) -> None:
+        """Initialize Prometheus metrics."""
+        try:
+            from prometheus_client import REGISTRY, Counter, Gauge, Histogram
+
+            self._registry = REGISTRY
+
+            # Define metrics
+            self._migrations_total = Counter(
+                "confiture_migrations_total",
+                "Total number of migrations executed",
+                ["version", "name", "status"],
+                registry=self._registry,
+            )
+
+            self._migration_duration = Histogram(
+                "confiture_migration_duration_seconds",
+                "Migration execution duration",
+                ["version"],
+                buckets=(0.1, 0.5, 1, 2, 5, 10, 30, 60, 120, 300),
+                registry=self._registry,
+            )
+
+            self._migration_errors = Counter(
+                "confiture_migration_errors_total",
+                "Total number of migration errors",
+                ["version", "error_type"],
+                registry=self._registry,
+            )
+
+            self._last_success = Gauge(
+                "confiture_migration_last_success_timestamp",
+                "Timestamp of last successful migration",
+                registry=self._registry,
+            )
+
+            self._initialized = True
+            logger.info("Prometheus metrics initialized")
+
+        except ImportError:
+            logger.warning(
+                "prometheus_client not installed. Install with: "
+                "pip install confiture[observability]"
+            )
+            self.config.enabled = False
+
+    @property
+    def is_enabled(self) -> bool:
+        """Check if metrics are enabled and initialized."""
+        return self.config.enabled and self._initialized
+
+    def start_server(self) -> None:
+        """Start Prometheus metrics HTTP server."""
+        if not self.is_enabled:
+            return
+
+        try:
+            from prometheus_client import start_http_server
+
+            start_http_server(self.config.port)
+            logger.info(f"Prometheus metrics server started on port {self.config.port}")
+
+        except Exception as e:
+            logger.error(f"Failed to start metrics server: {e}")
+
+    def record_migration(
+        self,
+        version: str,
+        name: str,
+        duration_seconds: float,
+        success: bool,
+        error: Exception | None = None,
+    ) -> None:
+        """Record migration execution metrics.
+
+        Args:
+            version: Migration version
+            name: Migration name
+            duration_seconds: Execution duration in seconds
+            success: Whether migration succeeded
+            error: Exception if failed (optional)
+        """
+        if not self.is_enabled:
+            return
+
+        import time
+
+        status = "success" if success else "error"
+        self._migrations_total.labels(version=version, name=name, status=status).inc()
+        self._migration_duration.labels(version=version).observe(duration_seconds)
+
+        if success:
+            self._last_success.set(time.time())
+        elif error:
+            error_type = type(error).__name__
+            self._migration_errors.labels(version=version, error_type=error_type).inc()
+
+    def record_error(self, version: str, error: Exception) -> None:
+        """Record a migration error.
+
+        Args:
+            version: Migration version
+            error: Exception that occurred
+        """
+        if not self.is_enabled:
+            return
+
+        error_type = type(error).__name__
+        self._migration_errors.labels(version=version, error_type=error_type).inc()
+
+
+def create_metrics(config: MetricsConfig | None = None) -> MigrationMetrics:
+    """Factory function to create metrics.
+
+    Args:
+        config: Metrics configuration (optional)
+
+    Returns:
+        Configured MigrationMetrics
+    """
+    return MigrationMetrics(config or MetricsConfig())

confiture/core/observability/tracing.py

@@ -0,0 +1,192 @@
+"""OpenTelemetry tracing for migrations.
+
+Provides optional tracing integration for migration execution.
+"""
+
+import logging
+from collections.abc import Generator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TracingConfig:
+    """Configuration for OpenTelemetry tracing."""
+
+    enabled: bool = False
+    service_name: str = "confiture"
+    endpoint: str | None = None  # OTLP endpoint
+    sample_rate: float = 1.0
+
+
+class MigrationTracer:
+    """OpenTelemetry tracer for migrations.
+
+    Provides tracing spans for migration operations when OpenTelemetry
+    is installed and configured.
+
+    Example:
+        >>> tracer = MigrationTracer(TracingConfig(enabled=True))
+        >>> with tracer.span("migration.apply", migration_id="001"):
+        ...     # Migration code
+        ...     pass
+    """
+
+    def __init__(self, config: TracingConfig):
+        """Initialize migration tracer.
+
+        Args:
+            config: Tracing configuration
+        """
+        self.config = config
+        self._tracer: Any = None
+        self._initialized = False
+
+        if config.enabled:
+            self._initialize_tracer()
+
+    def _initialize_tracer(self) -> None:
+        """Initialize OpenTelemetry tracer."""
+        try:
+            from opentelemetry import trace
+            from opentelemetry.sdk.resources import Resource
+            from opentelemetry.sdk.trace import TracerProvider
+            from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+            # Create resource
+            resource = Resource.create(
+                {
+                    "service.name": self.config.service_name,
+                    "service.version": "0.5.0",
+                }
+            )
+
+            # Create provider
+            provider = TracerProvider(resource=resource)
+
+            # Add exporter if endpoint configured
+            if self.config.endpoint:
+                try:
+                    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+                        OTLPSpanExporter,
+                    )
+
+                    exporter = OTLPSpanExporter(endpoint=self.config.endpoint)
+                    provider.add_span_processor(BatchSpanProcessor(exporter))
+                except ImportError:
+                    logger.warning(
+                        "OTLP exporter not installed. Install with: "
+                        "pip install opentelemetry-exporter-otlp"
+                    )
+
+            trace.set_tracer_provider(provider)
+            self._tracer = trace.get_tracer("confiture")
+            self._initialized = True
+
+            logger.info("OpenTelemetry tracing initialized")
+
+        except ImportError:
+            logger.warning(
+                "OpenTelemetry not installed. Install with: pip install confiture[observability]"
+            )
+            self.config.enabled = False
+
+    @property
+    def is_enabled(self) -> bool:
+        """Check if tracing is enabled and initialized."""
+        return self.config.enabled and self._initialized
+
+    @contextmanager
+    def span(
+        self,
+        name: str,
+        **attributes: Any,
+    ) -> Generator[Any, None, None]:
+        """Create a tracing span.
+
+        Args:
+            name: Span name
+            **attributes: Span attributes
+
+        Yields:
+            Span context (or None if disabled)
+        """
+        if not self.is_enabled or self._tracer is None:
+            yield None
+            return
+
+        with self._tracer.start_as_current_span(name) as span:
+            for key, value in attributes.items():
+                span.set_attribute(key, str(value))
+            yield span
+
+    def record_migration_start(
+        self,
+        migration_version: str,
+        migration_name: str,
+    ) -> Any:
+        """Create a span for migration start.
+
+        Args:
+            migration_version: Migration version
+            migration_name: Migration name
+
+        Returns:
+            Span context manager
+        """
+        return self.span(
+            "confiture.migration.execute",
+            migration_version=migration_version,
+            migration_name=migration_name,
+        )
+
+    def record_error(self, span: Any, error: Exception) -> None:
+        """Record error on span.
+
+        Args:
+            span: Active span
+            error: Exception that occurred
+        """
+        if span is None or not self.is_enabled:
+            return
+
+        try:
+            from opentelemetry import trace
+
+            span.set_status(trace.Status(trace.StatusCode.ERROR))
+            span.record_exception(error)
+        except ImportError:
+            pass
+
+    def record_success(self, span: Any, duration_ms: int) -> None:
+        """Record successful completion on span.
+
+        Args:
+            span: Active span
+            duration_ms: Duration in milliseconds
+        """
+        if span is None or not self.is_enabled:
+            return
+
+        try:
+            from opentelemetry import trace
+
+            span.set_attribute("duration_ms", duration_ms)
+            span.set_status(trace.Status(trace.StatusCode.OK))
+        except ImportError:
+            pass
+
+
+def create_tracer(config: TracingConfig | None = None) -> MigrationTracer:
+    """Factory function to create tracer.
+
+    Args:
+        config: Tracing configuration (optional)
+
+    Returns:
+        Configured MigrationTracer
+    """
+    return MigrationTracer(config or TracingConfig())