fraiseql-confiture 0.3.7__cp311-cp311-macosx_11_0_arm64.whl

confiture/core/observability/__init__.py

@@ -0,0 +1,44 @@
+"""Observability module for Confiture.
+
+Provides optional integrations with:
+- OpenTelemetry (tracing)
+- Prometheus (metrics)
+- Structured logging
+- Audit trail
+"""
+
+from confiture.core.observability.audit import (
+    AuditConfig,
+    AuditEntry,
+    AuditTrail,
+)
+from confiture.core.observability.logging import (
+    LoggingConfig,
+    StructuredLogger,
+    configure_logging,
+)
+from confiture.core.observability.metrics import (
+    MetricsConfig,
+    MigrationMetrics,
+    create_metrics,
+)
+from confiture.core.observability.tracing import (
+    MigrationTracer,
+    TracingConfig,
+    create_tracer,
+)
+
+__all__ = [
+    "TracingConfig",
+    "MigrationTracer",
+    "create_tracer",
+    "MetricsConfig",
+    "MigrationMetrics",
+    "create_metrics",
+    "LoggingConfig",
+    "StructuredLogger",
+    "configure_logging",
+    "AuditConfig",
+    "AuditTrail",
+    "AuditEntry",
+]

confiture/core/observability/audit.py

@@ -0,0 +1,323 @@
+"""Audit trail for migration compliance.
+
+Tracks who ran migrations, when, and the outcome for compliance purposes.
+"""
+
+import getpass
+import json
+import logging
+import os
+import socket
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+
+import psycopg
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AuditConfig:
+    """Configuration for audit trail."""
+
+    enabled: bool = True
+    table_name: str = "confiture_audit_log"
+
+
+@dataclass
+class AuditEntry:
+    """A single audit log entry."""
+
+    migration_version: str
+    migration_name: str
+    action: str  # "apply", "rollback", "dry_run"
+    status: str  # "started", "completed", "failed"
+    user: str
+    hostname: str
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    duration_ms: int | None = None
+    error_message: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "migration_version": self.migration_version,
+            "migration_name": self.migration_name,
+            "action": self.action,
+            "status": self.status,
+            "user": self.user,
+            "hostname": self.hostname,
+            "timestamp": self.timestamp.isoformat(),
+            "duration_ms": self.duration_ms,
+            "error_message": self.error_message,
+            "metadata": self.metadata,
+        }
+
+
+class AuditTrail:
+    """Records audit trail for compliance.
+
+    Tracks who ran migrations, when, from which machine, and whether
+    they succeeded or failed.
+
+    Example:
+        >>> audit = AuditTrail(conn, AuditConfig(enabled=True))
+        >>> audit.initialize()
+        >>> entry_id = audit.record_start("001", "create_users", "apply")
+        >>> # ... run migration ...
+        >>> audit.record_complete(entry_id, duration_ms=1500)
+    """
+
+    def __init__(
+        self,
+        connection: psycopg.Connection,
+        config: AuditConfig | None = None,
+    ):
+        """Initialize audit trail.
+
+        Args:
+            connection: Database connection
+            config: Audit configuration (optional)
+        """
+        self.connection = connection
+        self.config = config or AuditConfig()
+        self._initialized = False
+
+    @property
+    def is_enabled(self) -> bool:
+        """Check if audit trail is enabled."""
+        return self.config.enabled
+
+    def initialize(self) -> None:
+        """Create audit log table if it doesn't exist."""
+        if not self.config.enabled:
+            return
+
+        with self.connection.cursor() as cur:
+            cur.execute(f"""
+                CREATE TABLE IF NOT EXISTS {self.config.table_name} (
+                    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+                    migration_version VARCHAR(255) NOT NULL,
+                    migration_name VARCHAR(255) NOT NULL,
+                    action VARCHAR(50) NOT NULL,
+                    status VARCHAR(50) NOT NULL,
+                    username VARCHAR(255) NOT NULL,
+                    hostname VARCHAR(255) NOT NULL,
+                    started_at TIMESTAMPTZ NOT NULL,
+                    completed_at TIMESTAMPTZ,
+                    duration_ms INTEGER,
+                    error_message TEXT,
+                    metadata JSONB DEFAULT '{{}}'::jsonb
+                )
+            """)
+
+            cur.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_{self.config.table_name}_version
+                    ON {self.config.table_name}(migration_version)
+            """)
+
+            cur.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_{self.config.table_name}_started
+                    ON {self.config.table_name}(started_at DESC)
+            """)
+
+            cur.execute(f"""
+                CREATE INDEX IF NOT EXISTS idx_{self.config.table_name}_action
+                    ON {self.config.table_name}(action)
+            """)
+
+        self.connection.commit()
+        self._initialized = True
+        logger.info("Audit trail initialized")
+
+    def record_start(
+        self,
+        migration_version: str,
+        migration_name: str,
+        action: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> int:
+        """Record migration start.
+
+        Args:
+            migration_version: Migration version
+            migration_name: Migration name
+            action: Action type ("apply", "rollback", "dry_run")
+            metadata: Additional metadata (optional)
+
+        Returns:
+            Audit entry ID for later completion
+        """
+        if not self.config.enabled:
+            return -1
+
+        entry = AuditEntry(
+            migration_version=migration_version,
+            migration_name=migration_name,
+            action=action,
+            status="started",
+            user=self._get_current_user(),
+            hostname=self._get_hostname(),
+            metadata=metadata or {},
+        )
+
+        with self.connection.cursor() as cur:
+            cur.execute(
+                f"""
+                INSERT INTO {self.config.table_name}
+                    (migration_version, migration_name, action, status,
+                     username, hostname, started_at, metadata)
+                VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+                RETURNING id
+            """,
+                (
+                    entry.migration_version,
+                    entry.migration_name,
+                    entry.action,
+                    entry.status,
+                    entry.user,
+                    entry.hostname,
+                    entry.timestamp,
+                    json.dumps(entry.metadata),
+                ),
+            )
+            result = cur.fetchone()
+            entry_id = result[0] if result else -1
+
+        self.connection.commit()
+        return entry_id
+
+    def record_complete(
+        self,
+        entry_id: int,
+        duration_ms: int,
+        error_message: str | None = None,
+    ) -> None:
+        """Record migration completion.
+
+        Args:
+            entry_id: Audit entry ID from record_start
+            duration_ms: Duration in milliseconds
+            error_message: Error message if failed (optional)
+        """
+        if not self.config.enabled or entry_id < 0:
+            return
+
+        status = "failed" if error_message else "completed"
+
+        with self.connection.cursor() as cur:
+            cur.execute(
+                f"""
+                UPDATE {self.config.table_name}
+                SET status = %s,
+                    completed_at = %s,
+                    duration_ms = %s,
+                    error_message = %s
+                WHERE id = %s
+            """,
+                (
+                    status,
+                    datetime.now(UTC),
+                    duration_ms,
+                    error_message,
+                    entry_id,
+                ),
+            )
+
+        self.connection.commit()
+
+    def get_history(
+        self,
+        migration_version: str | None = None,
+        action: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Get audit history.
+
+        Args:
+            migration_version: Filter by version (optional)
+            action: Filter by action (optional)
+            limit: Maximum number of entries
+
+        Returns:
+            List of audit entries as dictionaries
+        """
+        if not self.config.enabled:
+            return []
+
+        conditions = []
+        params: list[Any] = []
+
+        if migration_version:
+            conditions.append("migration_version = %s")
+            params.append(migration_version)
+        if action:
+            conditions.append("action = %s")
+            params.append(action)
+
+        where_clause = ""
+        if conditions:
+            where_clause = "WHERE " + " AND ".join(conditions)
+
+        params.append(limit)
+
+        with self.connection.cursor() as cur:
+            cur.execute(
+                f"""
+                SELECT id, migration_version, migration_name, action, status,
+                       username, hostname, started_at, completed_at,
+                       duration_ms, error_message, metadata
+                FROM {self.config.table_name}
+                {where_clause}
+                ORDER BY started_at DESC
+                LIMIT %s
+            """,
+                params,
+            )
+
+            columns = [desc[0] for desc in cur.description]
+            return [dict(zip(columns, row, strict=True)) for row in cur.fetchall()]
+
+    def get_recent_failures(self, limit: int = 10) -> list[dict[str, Any]]:
+        """Get recent failed migrations.
+
+        Args:
+            limit: Maximum number of entries
+
+        Returns:
+            List of failed audit entries
+        """
+        if not self.config.enabled:
+            return []
+
+        with self.connection.cursor() as cur:
+            cur.execute(
+                f"""
+                SELECT id, migration_version, migration_name, action,
+                       username, hostname, started_at, error_message
+                FROM {self.config.table_name}
+                WHERE status = 'failed'
+                ORDER BY started_at DESC
+                LIMIT %s
+            """,
+                (limit,),
+            )
+
+            columns = [desc[0] for desc in cur.description]
+            return [dict(zip(columns, row, strict=True)) for row in cur.fetchall()]
+
+    def _get_current_user(self) -> str:
+        """Get current username."""
+        try:
+            return getpass.getuser()
+        except Exception:
+            return os.environ.get("USER", "unknown")
+
+    def _get_hostname(self) -> str:
+        """Get current hostname."""
+        try:
+            return socket.gethostname()
+        except Exception:
+            return "unknown"

confiture/core/observability/logging.py

@@ -0,0 +1,187 @@
+"""Structured JSON logging for migrations.
+
+Provides structured logging with correlation IDs for migration operations.
+"""
+
+import json
+import logging
+import sys
+import uuid
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+
+@dataclass
+class LoggingConfig:
+    """Configuration for structured logging."""
+
+    enabled: bool = True
+    format: str = "json"  # "json" or "text"
+    level: str = "INFO"
+    include_timestamp: bool = True
+    include_correlation_id: bool = True
+
+
+class StructuredFormatter(logging.Formatter):
+    """JSON formatter for structured logging."""
+
+    def __init__(self, config: LoggingConfig):
+        """Initialize structured formatter.
+
+        Args:
+            config: Logging configuration
+        """
+        super().__init__()
+        self.config = config
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record as JSON.
+
+        Args:
+            record: Log record to format
+
+        Returns:
+            JSON-formatted log string
+        """
+        log_data: dict[str, Any] = {
+            "level": record.levelname,
+            "message": record.getMessage(),
+            "logger": record.name,
+        }
+
+        if self.config.include_timestamp:
+            log_data["timestamp"] = datetime.now(UTC).isoformat()
+
+        if self.config.include_correlation_id:
+            log_data["correlation_id"] = getattr(record, "correlation_id", str(uuid.uuid4())[:8])
+
+        # Add extra fields from record
+        extra_fields = [
+            "migration_version",
+            "migration_name",
+            "duration_ms",
+            "rows_affected",
+            "operation",
+            "table_name",
+            "status",
+        ]
+        for field in extra_fields:
+            if hasattr(record, field):
+                log_data[field] = getattr(record, field)
+
+        # Add exception info
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+
+        return json.dumps(log_data)
+
+
+class StructuredLogger:
+    """Logger with structured output and correlation IDs.
+
+    Provides a logging interface that supports correlation IDs
+    and structured fields for migration operations.
+
+    Example:
+        >>> logger = StructuredLogger("confiture.migration")
+        >>> logger.set_correlation_id("abc123")
+        >>> logger.info("Starting migration", migration_version="001")
+    """
+
+    def __init__(self, name: str, config: LoggingConfig | None = None):
+        """Initialize structured logger.
+
+        Args:
+            name: Logger name
+            config: Logging configuration (optional)
+        """
+        self.config = config or LoggingConfig()
+        self._logger = logging.getLogger(name)
+        self._correlation_id: str | None = None
+
+    def _log(self, level: int, message: str, **kwargs: Any) -> None:
+        """Log with extra fields.
+
+        Args:
+            level: Log level
+            message: Log message
+            **kwargs: Extra fields to include
+        """
+        extra = {"correlation_id": self._correlation_id or str(uuid.uuid4())[:8]}
+        extra.update(kwargs)
+        self._logger.log(level, message, extra=extra)
+
+    def debug(self, message: str, **kwargs: Any) -> None:
+        """Log debug message."""
+        self._log(logging.DEBUG, message, **kwargs)
+
+    def info(self, message: str, **kwargs: Any) -> None:
+        """Log info message."""
+        self._log(logging.INFO, message, **kwargs)
+
+    def warning(self, message: str, **kwargs: Any) -> None:
+        """Log warning message."""
+        self._log(logging.WARNING, message, **kwargs)
+
+    def error(self, message: str, **kwargs: Any) -> None:
+        """Log error message."""
+        self._log(logging.ERROR, message, **kwargs)
+
+    def exception(self, message: str, **kwargs: Any) -> None:
+        """Log exception with traceback."""
+        extra = {"correlation_id": self._correlation_id or str(uuid.uuid4())[:8]}
+        extra.update(kwargs)
+        self._logger.exception(message, extra=extra)
+
+    def set_correlation_id(self, correlation_id: str) -> None:
+        """Set correlation ID for subsequent logs.
+
+        Args:
+            correlation_id: Correlation ID to use
+        """
+        self._correlation_id = correlation_id
+
+    def clear_correlation_id(self) -> None:
+        """Clear the correlation ID."""
+        self._correlation_id = None
+
+    def new_correlation_id(self) -> str:
+        """Generate and set a new correlation ID.
+
+        Returns:
+            The new correlation ID
+        """
+        self._correlation_id = str(uuid.uuid4())[:8]
+        return self._correlation_id
+
+
+def configure_logging(config: LoggingConfig | None = None) -> None:
+    """Configure structured logging for Confiture.
+
+    Args:
+        config: Logging configuration (optional)
+    """
+    config = config or LoggingConfig()
+
+    # Get root logger for confiture
+    logger = logging.getLogger("confiture")
+    logger.setLevel(getattr(logging, config.level))
+
+    # Remove existing handlers
+    logger.handlers.clear()
+
+    # Add handler with appropriate formatter
+    handler = logging.StreamHandler(sys.stderr)
+
+    if config.format == "json":
+        handler.setFormatter(StructuredFormatter(config))
+    else:
+        handler.setFormatter(
+            logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+        )
+
+    logger.addHandler(handler)
+
+    # Prevent propagation to root logger
+    logger.propagate = False