puffinflow 2.dev0__py3-none-any.whl

puffinflow/core/observability/interfaces.py

@@ -0,0 +1,196 @@
+import uuid
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional
+
+
+class SpanType(Enum):
+    """Types of spans for categorization"""
+
+    WORKFLOW = "workflow"
+    STATE = "state"
+    RESOURCE = "resource"
+    BUSINESS = "business"
+    SYSTEM = "system"
+
+
+class MetricType(Enum):
+    """Types of metrics"""
+
+    COUNTER = "counter"
+    GAUGE = "gauge"
+    HISTOGRAM = "histogram"
+
+
+class AlertSeverity(Enum):
+    """Alert severity levels"""
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+    CRITICAL = "critical"
+
+
+@dataclass
+class SpanContext:
+    """Correlation context for distributed tracing"""
+
+    trace_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    span_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    parent_span_id: Optional[str] = None
+    workflow_id: Optional[str] = None
+    agent_name: Optional[str] = None
+    state_name: Optional[str] = None
+    user_id: Optional[str] = None
+    session_id: Optional[str] = None
+
+    def child_context(self) -> "SpanContext":
+        """Create child span context"""
+        return SpanContext(
+            trace_id=self.trace_id,
+            span_id=str(uuid.uuid4()),
+            parent_span_id=self.span_id,
+            workflow_id=self.workflow_id,
+            agent_name=self.agent_name,
+            state_name=self.state_name,
+            user_id=self.user_id,
+            session_id=self.session_id,
+        )
+
+
+@dataclass
+class ObservabilityEvent:
+    """Structured observability event"""
+
+    timestamp: datetime
+    event_type: str
+    source: str
+    level: str
+    message: str
+    attributes: dict[str, Any] = field(default_factory=dict)
+    span_context: Optional[SpanContext] = None
+
+
+class Span(ABC):
+    """Abstract span interface"""
+
+    @abstractmethod
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Set span attribute"""
+
+    @abstractmethod
+    def set_status(self, status: str, description: Optional[str] = None) -> None:
+        """Set span status"""
+
+    @abstractmethod
+    def add_event(self, name: str, attributes: Optional[dict[str, Any]] = None) -> None:
+        """Add event to span"""
+
+    @abstractmethod
+    def record_exception(self, exception: Exception) -> None:
+        """Record exception in span"""
+
+    @abstractmethod
+    def end(self) -> None:
+        """End the span"""
+
+    @property
+    @abstractmethod
+    def context(self) -> SpanContext:
+        """Get span context"""
+
+
+class TracingProvider(ABC):
+    """Abstract tracing provider"""
+
+    @abstractmethod
+    def start_span(
+        self,
+        name: str,
+        span_type: SpanType = SpanType.SYSTEM,
+        parent: Optional[SpanContext] = None,
+        **attributes: Any,
+    ) -> Span:
+        """Start a new span"""
+
+    @abstractmethod
+    def get_current_span(self) -> Optional[Span]:
+        """Get current active span"""
+
+    @contextmanager
+    def span(
+        self,
+        name: str,
+        span_type: SpanType = SpanType.SYSTEM,
+        parent: Optional[SpanContext] = None,
+        **attributes: Any,
+    ) -> Iterator[Span]:
+        """Context manager for spans"""
+        span = self.start_span(name, span_type, parent, **attributes)
+        try:
+            yield span
+            span.set_status("ok")
+        except Exception as e:
+            span.record_exception(e)
+            raise
+        finally:
+            span.end()
+
+
+class Metric(ABC):
+    """Abstract metric interface"""
+
+    @abstractmethod
+    def record(self, value: float, **labels: Any) -> None:
+        """Record metric value"""
+
+
+class MetricsProvider(ABC):
+    """Abstract metrics provider"""
+
+    @abstractmethod
+    def counter(
+        self, name: str, description: str = "", labels: Optional[list[str]] = None
+    ) -> Metric:
+        """Create counter metric"""
+
+    @abstractmethod
+    def gauge(
+        self, name: str, description: str = "", labels: Optional[list[str]] = None
+    ) -> Metric:
+        """Create gauge metric"""
+
+    @abstractmethod
+    def histogram(
+        self, name: str, description: str = "", labels: Optional[list[str]] = None
+    ) -> Metric:
+        """Create histogram metric"""
+
+    @abstractmethod
+    def export_metrics(self) -> str:
+        """Export metrics in Prometheus format"""
+
+
+class AlertingProvider(ABC):
+    """Abstract alerting provider"""
+
+    @abstractmethod
+    async def send_alert(
+        self,
+        message: str,
+        severity: AlertSeverity,
+        attributes: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Send alert"""
+
+
+class EventProcessor(ABC):
+    """Abstract event processor"""
+
+    @abstractmethod
+    async def process_event(self, event: ObservabilityEvent) -> None:
+        """Process observability event"""

puffinflow/core/observability/metrics.py

@@ -0,0 +1,137 @@
+import threading
+from typing import Any, Optional
+
+from prometheus_client import CollectorRegistry, generate_latest
+from prometheus_client import Counter as PrometheusCounter
+from prometheus_client import Gauge as PrometheusGauge
+from prometheus_client import Histogram as PrometheusHistogram
+
+from .config import MetricsConfig
+from .interfaces import Metric, MetricsProvider, MetricType
+
+
+class PrometheusMetric(Metric):
+    """Prometheus metric wrapper"""
+
+    def __init__(
+        self, prometheus_metric: Any, metric_type: MetricType, cardinality_limit: int
+    ) -> None:
+        self._prometheus_metric = prometheus_metric
+        self._metric_type = metric_type
+        self._cardinality_limit = cardinality_limit
+        self._series_count = 0
+        self._lock = threading.Lock()
+
+    def record(self, value: float, **labels: Any) -> None:
+        """Record metric value"""
+        # Basic cardinality protection
+        with self._lock:
+            if self._series_count >= self._cardinality_limit:
+                return  # Skip to prevent memory issues
+
+            # Convert label values to strings
+            str_labels = {k: str(v) for k, v in labels.items() if v is not None}
+
+            try:
+                if str_labels:
+                    if self._metric_type == MetricType.COUNTER:
+                        self._prometheus_metric.labels(**str_labels).inc(value)
+                    elif self._metric_type == MetricType.GAUGE:
+                        self._prometheus_metric.labels(**str_labels).set(value)
+                    elif self._metric_type == MetricType.HISTOGRAM:
+                        self._prometheus_metric.labels(**str_labels).observe(value)
+                else:
+                    if self._metric_type == MetricType.COUNTER:
+                        self._prometheus_metric.inc(value)
+                    elif self._metric_type == MetricType.GAUGE:
+                        self._prometheus_metric.set(value)
+                    elif self._metric_type == MetricType.HISTOGRAM:
+                        self._prometheus_metric.observe(value)
+
+                self._series_count += 1
+
+            except Exception as e:
+                # Log error but don't fail the application
+                print(f"Failed to record metric: {e}")
+
+
+class PrometheusMetricsProvider(MetricsProvider):
+    """Prometheus metrics provider"""
+
+    def __init__(self, config: MetricsConfig):
+        self.config = config
+        self._registry = CollectorRegistry()
+        self._metrics_cache: dict[str, Metric] = {}
+        self._lock = threading.Lock()
+
+    def counter(
+        self, name: str, description: str = "", labels: Optional[list[str]] = None
+    ) -> Metric:
+        """Create counter metric"""
+        return self._get_or_create_metric(
+            name, MetricType.COUNTER, description, labels or []
+        )
+
+    def gauge(
+        self, name: str, description: str = "", labels: Optional[list[str]] = None
+    ) -> Metric:
+        """Create gauge metric"""
+        return self._get_or_create_metric(
+            name, MetricType.GAUGE, description, labels or []
+        )
+
+    def histogram(
+        self, name: str, description: str = "", labels: Optional[list[str]] = None
+    ) -> Metric:
+        """Create histogram metric"""
+        return self._get_or_create_metric(
+            name, MetricType.HISTOGRAM, description, labels or []
+        )
+
+    def _get_or_create_metric(
+        self, name: str, metric_type: MetricType, description: str, labels: list[str]
+    ) -> Metric:
+        """Get or create metric"""
+        metric_key = f"{self.config.namespace}_{name}"
+
+        with self._lock:
+            if metric_key in self._metrics_cache:
+                return self._metrics_cache[metric_key]
+
+            labelnames = labels or []
+
+            prometheus_metric: Any
+            if metric_type == MetricType.COUNTER:
+                prometheus_metric = PrometheusCounter(
+                    metric_key,
+                    description,
+                    labelnames=labelnames,
+                    registry=self._registry,
+                )
+            elif metric_type == MetricType.GAUGE:
+                prometheus_metric = PrometheusGauge(
+                    metric_key,
+                    description,
+                    labelnames=labelnames,
+                    registry=self._registry,
+                )
+            elif metric_type == MetricType.HISTOGRAM:
+                prometheus_metric = PrometheusHistogram(
+                    metric_key,
+                    description,
+                    labelnames=labelnames,
+                    registry=self._registry,
+                )
+            else:
+                raise ValueError(f"Unsupported metric type: {metric_type}")
+
+            metric = PrometheusMetric(
+                prometheus_metric, metric_type, self.config.cardinality_limit
+            )
+            self._metrics_cache[metric_key] = metric
+            return metric
+
+    def export_metrics(self) -> str:
+        """Export metrics in Prometheus format"""
+        result: bytes = generate_latest(self._registry)
+        return result.decode("utf-8")

puffinflow/core/observability/tracing.py

@@ -0,0 +1,209 @@
+import threading
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any, Optional
+
+try:
+    from opentelemetry import trace
+    from opentelemetry.exporter.jaeger.thrift import JaegerExporter
+    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+    from opentelemetry.sdk.resources import Resource
+    from opentelemetry.sdk.trace import TracerProvider
+    from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter
+    from opentelemetry.trace import Status, StatusCode
+
+    _OPENTELEMETRY_AVAILABLE = True
+except ImportError:
+    # Create mock classes for when OpenTelemetry is not available
+    trace = None
+    JaegerExporter = None
+    OTLPSpanExporter = None
+    Resource = None
+    TracerProvider = None
+    BatchSpanProcessor = None
+    ConsoleSpanExporter = None
+    Status = None
+    StatusCode = None
+    _OPENTELEMETRY_AVAILABLE = False
+
+from .config import TracingConfig
+from .interfaces import Span, SpanContext, SpanType, TracingProvider
+
+
+class OpenTelemetrySpan(Span):
+    """OpenTelemetry span implementation"""
+
+    def __init__(self, otel_span: Any, span_context: SpanContext):
+        self._span = otel_span
+        self._context = span_context
+        self._start_time = time.time()
+
+        # Set workflow context attributes if OpenTelemetry is available
+        if _OPENTELEMETRY_AVAILABLE and self._span:
+            if span_context.workflow_id:
+                self._span.set_attribute("workflow.id", span_context.workflow_id)
+            if span_context.agent_name:
+                self._span.set_attribute("agent.name", span_context.agent_name)
+            if span_context.state_name:
+                self._span.set_attribute("state.name", span_context.state_name)
+            if span_context.user_id:
+                self._span.set_attribute("user.id", span_context.user_id)
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """Set span attribute"""
+        if _OPENTELEMETRY_AVAILABLE and self._span and key and value is not None:
+            if isinstance(value, (dict, list)):
+                value = str(value)
+            self._span.set_attribute(key, value)
+
+    def set_status(self, status: str, description: Optional[str] = None) -> None:
+        """Set span status"""
+        if _OPENTELEMETRY_AVAILABLE and self._span:
+            if status.lower() in ["ok", "success"]:
+                self._span.set_status(Status(StatusCode.OK, description))
+            elif status.lower() in ["error", "failed"]:
+                self._span.set_status(Status(StatusCode.ERROR, description))
+
+    def add_event(self, name: str, attributes: Optional[dict[str, Any]] = None) -> None:
+        """Add event to span"""
+        if _OPENTELEMETRY_AVAILABLE and self._span:
+            event_attrs = attributes or {}
+            event_attrs = {k: v for k, v in event_attrs.items() if v is not None}
+            self._span.add_event(name, event_attrs)
+
+    def record_exception(self, exception: Exception) -> None:
+        """Record exception in span"""
+        if _OPENTELEMETRY_AVAILABLE and self._span:
+            self._span.record_exception(exception)
+            self.set_status("error", str(exception))
+
+    def end(self) -> None:
+        """End span"""
+        duration = time.time() - self._start_time
+        self.set_attribute("span.duration_ms", duration * 1000)
+        if _OPENTELEMETRY_AVAILABLE and self._span:
+            self._span.end()
+
+    @property
+    def context(self) -> SpanContext:
+        """Get span context"""
+        return self._context
+
+
+class OpenTelemetryTracingProvider(TracingProvider):
+    """OpenTelemetry tracing provider"""
+
+    def __init__(self, config: TracingConfig):
+        self.config = config
+        self._current_context = threading.local()
+        self._tracer: Any = None
+        if _OPENTELEMETRY_AVAILABLE:
+            self._setup_tracing()
+
+    def _setup_tracing(self) -> None:
+        """Setup OpenTelemetry tracing"""
+        if not _OPENTELEMETRY_AVAILABLE:
+            return
+
+        resource = Resource.create(
+            {
+                "service.name": self.config.service_name,
+                "service.version": self.config.service_version,
+            }
+        )
+
+        provider = TracerProvider(resource=resource)
+        trace.set_tracer_provider(provider)
+
+        # Setup exporters
+        processors = []
+
+        if self.config.otlp_endpoint:
+            otlp_exporter = OTLPSpanExporter(endpoint=self.config.otlp_endpoint)
+            processors.append(BatchSpanProcessor(otlp_exporter))
+
+        if self.config.jaeger_endpoint:
+            jaeger_exporter = JaegerExporter(
+                agent_host_name=self.config.jaeger_endpoint.split(":")[0],
+                agent_port=(
+                    int(self.config.jaeger_endpoint.split(":")[1])
+                    if ":" in self.config.jaeger_endpoint
+                    else 6831
+                ),
+            )
+            processors.append(BatchSpanProcessor(jaeger_exporter))
+
+        if self.config.console_enabled:
+            console_exporter = ConsoleSpanExporter()
+            processors.append(BatchSpanProcessor(console_exporter))
+
+        for processor in processors:
+            provider.add_span_processor(processor)
+
+        self._tracer = trace.get_tracer(
+            instrumenting_module_name="puffinflow.observability",
+            instrumenting_library_version="1.0.0",
+        )
+
+    def start_span(
+        self,
+        name: str,
+        span_type: SpanType = SpanType.SYSTEM,
+        parent: Optional[SpanContext] = None,
+        **attributes: Any,
+    ) -> Span:
+        """Start new span"""
+        # Create span context
+        if parent:
+            span_context = parent.child_context()
+        else:
+            current_span = self.get_current_span()
+            if current_span:
+                span_context = current_span.context.child_context()
+            else:
+                span_context = SpanContext()
+
+        # Start OpenTelemetry span if available
+        otel_span = None
+        if _OPENTELEMETRY_AVAILABLE and self._tracer:
+            otel_span = self._tracer.start_span(name)
+
+        # Create wrapper
+        span = OpenTelemetrySpan(otel_span, span_context)
+
+        # Set additional attributes
+        span.set_attribute("span.type", span_type.value)
+        for key, value in attributes.items():
+            span.set_attribute(key, value)
+
+        self._set_current_span(span)
+        return span
+
+    def get_current_span(self) -> Optional[Span]:
+        """Get current active span"""
+        return getattr(self._current_context, "current_span", None)
+
+    def _set_current_span(self, span: Optional[Span]) -> None:
+        """Set current span in context"""
+        self._current_context.current_span = span
+
+    @contextmanager
+    def span(
+        self,
+        name: str,
+        span_type: SpanType = SpanType.SYSTEM,
+        parent: Optional[SpanContext] = None,
+        **attributes: Any,
+    ) -> Iterator[Span]:
+        """Context manager for spans"""
+        span = self.start_span(name, span_type, parent, **attributes)
+        try:
+            yield span
+            span.set_status("ok")
+        except Exception as e:
+            span.record_exception(e)
+            raise
+        finally:
+            span.end()
+            self._set_current_span(None)

puffinflow/core/reliability/__init__.py

@@ -0,0 +1,27 @@
+"""Reliability patterns for production workflows."""
+
+# Import submodules for import path tests
+from . import bulkhead, circuit_breaker, leak_detector
+from .bulkhead import Bulkhead, BulkheadConfig, BulkheadFullError
+from .circuit_breaker import (
+    CircuitBreaker,
+    CircuitBreakerConfig,
+    CircuitBreakerError,
+    CircuitState,
+)
+from .leak_detector import ResourceLeak, ResourceLeakDetector
+
+__all__ = [
+    "Bulkhead",
+    "BulkheadConfig",
+    "BulkheadFullError",
+    "CircuitBreaker",
+    "CircuitBreakerConfig",
+    "CircuitBreakerError",
+    "CircuitState",
+    "ResourceLeak",
+    "ResourceLeakDetector",
+    "bulkhead",
+    "circuit_breaker",
+    "leak_detector",
+]

puffinflow/core/reliability/bulkhead.py

@@ -0,0 +1,96 @@
+"""Bulkhead pattern for resource isolation."""
+
+import asyncio
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class BulkheadConfig:
+    name: str
+    max_concurrent: int
+    max_queue_size: int = 100
+    timeout: float = 30.0
+
+
+class BulkheadFullError(Exception):
+    """Raised when bulkhead is at capacity"""
+
+    pass
+
+
+class Bulkhead:
+    """Isolate resources to prevent cascading failures"""
+
+    def __init__(self, config: BulkheadConfig):
+        self.config = config
+        self._semaphore = asyncio.Semaphore(config.max_concurrent)
+        self._queue_size = 0
+        self._active_tasks: set[asyncio.Task] = set()
+
+    @asynccontextmanager
+    async def isolate(self) -> AsyncIterator[None]:
+        """Execute function within bulkhead constraints"""
+        # Check queue capacity
+        if self._queue_size >= self.config.max_queue_size:
+            raise BulkheadFullError(f"Bulkhead {self.config.name} queue full")
+
+        self._queue_size += 1
+        try:
+            # Wait for semaphore with timeout
+            try:
+                await asyncio.wait_for(
+                    self._semaphore.acquire(), timeout=self.config.timeout
+                )
+            except asyncio.TimeoutError as e:
+                raise BulkheadFullError(
+                    f"Bulkhead {self.config.name} timeout waiting for slot"
+                ) from e
+
+            try:
+                yield
+            finally:
+                self._semaphore.release()
+        finally:
+            self._queue_size -= 1
+
+    def get_metrics(self) -> dict[str, Any]:
+        """Get bulkhead metrics"""
+        return {
+            "name": self.config.name,
+            "max_concurrent": self.config.max_concurrent,
+            "available_slots": self._semaphore._value,
+            "queue_size": self._queue_size,
+            "max_queue_size": self.config.max_queue_size,
+            "active_tasks": len(self._active_tasks),
+        }
+
+
+# Global bulkhead registry
+class BulkheadRegistry:
+    """Simple registry for bulkheads"""
+
+    def __init__(self) -> None:
+        self._bulkheads: dict[str, Bulkhead] = {}
+
+    def get_or_create(
+        self, name: str, config: Optional[BulkheadConfig] = None
+    ) -> Bulkhead:
+        """Get existing or create new bulkhead"""
+        if name not in self._bulkheads:
+            if config is None:
+                config = BulkheadConfig(name=name, max_concurrent=5)
+            self._bulkheads[name] = Bulkhead(config)
+        return self._bulkheads[name]
+
+    def get_all_metrics(self) -> dict[str, dict[str, Any]]:
+        """Get metrics for all bulkheads"""
+        return {
+            name: bulkhead.get_metrics() for name, bulkhead in self._bulkheads.items()
+        }
+
+
+# Global registry instance
+bulkhead_registry = BulkheadRegistry()