agentreplay 0.1.2__py3-none-any.whl

agentreplay/bootstrap.py

@@ -0,0 +1,202 @@
+# Copyright 2025 Sushanth (https://github.com/sushanthpy)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Bootstrap module for zero-code auto-instrumentation.
+
+This module is called by the .pth file on Python startup when AGENTREPLAY_ENABLED=true.
+It initializes OpenTelemetry instrumentation with minimal overhead.
+
+Environment Variables:
+    AGENTREPLAY_ENABLED: Set to 'true' to enable auto-instrumentation
+    AGENTREPLAY_SERVICE_NAME: Service name for traces (default: 'agentreplay-app')
+    AGENTREPLAY_OTLP_ENDPOINT: OTLP gRPC endpoint (default: 'localhost:47117')
+    AGENTREPLAY_PROJECT_ID: Project ID for traces
+    AGENTREPLAY_TENANT_ID: Tenant ID for traces (default: 1)
+    AGENTREPLAY_DEBUG: Enable debug logging (default: false)
+    AGENTREPLAY_CAPTURE_CONTENT: Capture LLM request/response content (default: true)
+    OTEL_EXPORTER_OTLP_ENDPOINT: Standard OTEL endpoint override
+
+Example:
+    # Option 1: Automatic via .pth file
+    $ export AGENTREPLAY_ENABLED=true
+    $ export AGENTREPLAY_PROJECT_ID=27986
+    $ python my_app.py  # Auto-instrumented!
+    
+    # Option 2: Manual initialization
+    >>> from agentreplay.bootstrap import init_otel_instrumentation
+    >>> init_otel_instrumentation()
+"""
+
+import os
+import logging
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# Global flag to prevent double-initialization
+_initialized = False
+
+
+def init_otel_instrumentation(
+    service_name: Optional[str] = None,
+    otlp_endpoint: Optional[str] = None,
+    project_id: Optional[int] = None,
+    tenant_id: Optional[int] = None,
+    capture_content: Optional[bool] = None,
+    debug: Optional[bool] = None,
+) -> bool:
+    """Initialize OpenTelemetry instrumentation.
+    
+    This function sets up the OpenTelemetry SDK with OTLP exporter and
+    automatically instruments all available libraries.
+    
+    Args:
+        service_name: Service name (default: from env or 'agentreplay-app')
+        otlp_endpoint: OTLP endpoint (default: from env or 'localhost:47117')
+        project_id: Project ID (default: from env)
+        tenant_id: Tenant ID (default: from env or 1)
+        capture_content: Capture LLM content (default: from env or True)
+        debug: Enable debug logging (default: from env or False)
+    
+    Returns:
+        True if initialization succeeded, False if already initialized
+    
+    Example:
+        >>> from agentreplay.bootstrap import init_otel_instrumentation
+        >>> init_otel_instrumentation(
+        ...     service_name="my-agent",
+        ...     project_id=27986
+        ... )
+    """
+    global _initialized
+    
+    if _initialized:
+        logger.debug("Agentreplay already initialized, skipping")
+        return False
+    
+    # Read from environment with fallbacks
+    service_name = service_name or os.getenv("AGENTREPLAY_SERVICE_NAME", "agentreplay-app")
+    otlp_endpoint = otlp_endpoint or os.getenv(
+        "AGENTREPLAY_OTLP_ENDPOINT",
+        os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "localhost:47117")
+    )
+    
+    # Project/tenant IDs
+    if project_id is None:
+        project_id_str = os.getenv("AGENTREPLAY_PROJECT_ID", "0")
+        try:
+            project_id = int(project_id_str)
+        except ValueError:
+            logger.warning(f"Invalid AGENTREPLAY_PROJECT_ID: {project_id_str}, using 0")
+            project_id = 0
+    
+    if tenant_id is None:
+        tenant_id_str = os.getenv("AGENTREPLAY_TENANT_ID", "1")
+        try:
+            tenant_id = int(tenant_id_str)
+        except ValueError:
+            logger.warning(f"Invalid AGENTREPLAY_TENANT_ID: {tenant_id_str}, using 1")
+            tenant_id = 1
+    
+    # Flags
+    if capture_content is None:
+        capture_content = os.getenv("AGENTREPLAY_CAPTURE_CONTENT", "true").lower() in {
+            "1", "true", "yes"
+        }
+    
+    if debug is None:
+        debug = os.getenv("AGENTREPLAY_DEBUG", "false").lower() in {"1", "true", "yes"}
+    
+    if debug:
+        logging.basicConfig(level=logging.DEBUG)
+        logger.setLevel(logging.DEBUG)
+    
+    try:
+        # Import here to avoid loading OTEL on every Python startup
+        from agentreplay.auto_instrument import setup_instrumentation
+        
+        logger.info(f"🚀 Initializing Agentreplay for service: {service_name}")
+        logger.debug(f"   OTLP Endpoint: {otlp_endpoint}")
+        logger.debug(f"   Project ID: {project_id}")
+        logger.debug(f"   Tenant ID: {tenant_id}")
+        logger.debug(f"   Capture Content: {capture_content}")
+        
+        setup_instrumentation(
+            service_name=service_name,
+            otlp_endpoint=otlp_endpoint,
+            tenant_id=tenant_id,
+            project_id=project_id,
+            capture_content=capture_content,
+            debug=debug,
+        )
+        
+        _initialized = True
+        logger.info("✅ Agentreplay initialization complete")
+        return True
+        
+    except Exception as e:
+        logger.error(f"❌ Failed to initialize Agentreplay: {e}", exc_info=debug)
+        # Don't crash the user's app - fail open
+        return False
+
+
+def _auto_init():
+    """Called by the .pth file on Python startup.
+    
+    Only initializes if AGENTREPLAY_ENABLED=true to avoid overhead.
+    This is the entry point for zero-code auto-instrumentation.
+    
+    Automatically loads .env file if present for developer convenience.
+    """
+    # Try to load .env file first (if python-dotenv is available)
+    if os.path.exists('.env'):
+        try:
+            from dotenv import load_dotenv
+            load_dotenv('.env', override=False)  # Don't override existing env vars
+        except ImportError:
+            pass  # python-dotenv not installed, no problem
+        except Exception as e:
+            pass  # Any other error, fail silently
+    
+    if not os.getenv("AGENTREPLAY_ENABLED", "").lower() in {"1", "true", "yes"}:
+        # Not enabled, skip silently
+        return
+    
+    try:
+        init_otel_instrumentation(debug=True)  # Enable debug to see what's happening
+    except Exception as e:
+        # Fail open - don't break user's app if SDK has issues
+        import sys
+        print(f"Agentreplay auto-init failed: {e}", file=sys.stderr)
+        pass
+
+
+def is_initialized() -> bool:
+    """Check if Agentreplay has been initialized.
+    
+    Returns:
+        True if initialized, False otherwise
+    """
+    return _initialized
+
+
+def reset_initialization():
+    """Reset initialization state (primarily for testing).
+    
+    Warning:
+        This does not actually tear down the OTEL SDK, it only resets
+        the initialization flag. Use only in tests.
+    """
+    global _initialized
+    _initialized = False

agentreplay/circuit_breaker.py

@@ -0,0 +1,300 @@
+# Copyright 2025 Sushanth (https://github.com/sushanthpy)
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Circuit Breaker pattern for Agentreplay backend resilience.
+
+This module implements a circuit breaker to prevent cascading failures when
+the Agentreplay backend is unavailable. The circuit breaker has three states:
+
+- CLOSED: Normal operation, requests pass through
+- OPEN: Backend is failing, requests are rejected immediately
+- HALF_OPEN: Testing recovery, allowing limited requests through
+
+The circuit breaker helps maintain application responsiveness during backend
+outages by failing fast rather than blocking on retries.
+
+Usage:
+    >>> from agentreplay.circuit_breaker import CircuitBreaker, CircuitBreakerOpen
+    >>> 
+    >>> breaker = CircuitBreaker()
+    >>> 
+    >>> try:
+    ...     with breaker:
+    ...         send_spans_to_backend()
+    ... except CircuitBreakerOpen:
+    ...     logger.warning("Agentreplay backend unavailable, dropping spans")
+"""
+
+import time
+import threading
+import logging
+from enum import Enum
+from typing import Optional, Callable, Any
+from functools import wraps
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitState(Enum):
+    """Circuit breaker states."""
+    CLOSED = "closed"       # Normal operation
+    OPEN = "open"           # Failing, reject requests
+    HALF_OPEN = "half_open" # Testing recovery
+
+
+class CircuitBreakerOpen(Exception):
+    """Exception raised when circuit breaker is open."""
+    pass
+
+
+class CircuitBreaker:
+    """Thread-safe circuit breaker for backend resilience.
+    
+    Args:
+        failure_threshold: Number of failures before opening circuit (default: 5)
+        recovery_timeout: Seconds before attempting recovery (default: 30)
+        success_threshold: Successes needed to close circuit from half-open (default: 3)
+        failure_window: Time window in seconds for counting failures (default: 60)
+    
+    Example:
+        >>> breaker = CircuitBreaker(failure_threshold=3, recovery_timeout=60)
+        >>> 
+        >>> @breaker.protect
+        ... def send_to_backend():
+        ...     response = requests.post(...)
+        ...     response.raise_for_status()
+        ...     return response
+    """
+    
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        recovery_timeout: float = 30.0,
+        success_threshold: int = 3,
+        failure_window: float = 60.0,
+    ):
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout = recovery_timeout
+        self.success_threshold = success_threshold
+        self.failure_window = failure_window
+        
+        self._state = CircuitState.CLOSED
+        self._failure_count = 0
+        self._success_count = 0
+        self._last_failure_time: Optional[float] = None
+        self._last_state_change: float = time.time()
+        self._lock = threading.Lock()
+        
+        # Track failure times for windowed counting
+        self._failure_times: list[float] = []
+    
+    @property
+    def state(self) -> CircuitState:
+        """Get current circuit state."""
+        with self._lock:
+            self._check_state_transition()
+            return self._state
+    
+    @property
+    def is_closed(self) -> bool:
+        """Check if circuit is closed (normal operation)."""
+        return self.state == CircuitState.CLOSED
+    
+    @property
+    def is_open(self) -> bool:
+        """Check if circuit is open (rejecting requests)."""
+        return self.state == CircuitState.OPEN
+    
+    def _check_state_transition(self) -> None:
+        """Check if state should transition (called with lock held)."""
+        now = time.time()
+        
+        if self._state == CircuitState.OPEN:
+            # Check if recovery timeout has passed
+            if now - self._last_state_change >= self.recovery_timeout:
+                self._transition_to(CircuitState.HALF_OPEN)
+        
+        elif self._state == CircuitState.CLOSED:
+            # Clean up old failures outside the window
+            cutoff = now - self.failure_window
+            self._failure_times = [t for t in self._failure_times if t > cutoff]
+            self._failure_count = len(self._failure_times)
+    
+    def _transition_to(self, new_state: CircuitState) -> None:
+        """Transition to a new state (called with lock held)."""
+        old_state = self._state
+        self._state = new_state
+        self._last_state_change = time.time()
+        
+        if new_state == CircuitState.CLOSED:
+            self._failure_count = 0
+            self._failure_times.clear()
+            self._success_count = 0
+        elif new_state == CircuitState.HALF_OPEN:
+            self._success_count = 0
+        
+        logger.info(
+            f"Circuit breaker state change: {old_state.value} -> {new_state.value}"
+        )
+    
+    def record_success(self) -> None:
+        """Record a successful request."""
+        with self._lock:
+            if self._state == CircuitState.HALF_OPEN:
+                self._success_count += 1
+                if self._success_count >= self.success_threshold:
+                    self._transition_to(CircuitState.CLOSED)
+    
+    def record_failure(self, error: Optional[Exception] = None) -> None:
+        """Record a failed request."""
+        now = time.time()
+        
+        with self._lock:
+            self._last_failure_time = now
+            
+            if self._state == CircuitState.CLOSED:
+                self._failure_times.append(now)
+                self._failure_count = len(self._failure_times)
+                
+                if self._failure_count >= self.failure_threshold:
+                    self._transition_to(CircuitState.OPEN)
+                    logger.warning(
+                        f"Circuit breaker opened after {self._failure_count} failures. "
+                        f"Will retry after {self.recovery_timeout}s."
+                    )
+            
+            elif self._state == CircuitState.HALF_OPEN:
+                # Any failure in half-open state reopens the circuit
+                self._transition_to(CircuitState.OPEN)
+                logger.warning("Circuit breaker reopened after recovery test failure.")
+    
+    def allow_request(self) -> bool:
+        """Check if a request should be allowed through.
+        
+        Returns:
+            True if request is allowed, False if circuit is open
+        """
+        with self._lock:
+            self._check_state_transition()
+            
+            if self._state == CircuitState.CLOSED:
+                return True
+            elif self._state == CircuitState.OPEN:
+                return False
+            else:  # HALF_OPEN
+                return True  # Allow test requests through
+    
+    def __enter__(self) -> "CircuitBreaker":
+        """Context manager entry - check if request is allowed."""
+        if not self.allow_request():
+            raise CircuitBreakerOpen(
+                f"Circuit breaker is open. Recovery in "
+                f"{self.recovery_timeout - (time.time() - self._last_state_change):.1f}s"
+            )
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        """Context manager exit - record success or failure."""
+        if exc_type is None:
+            self.record_success()
+        else:
+            self.record_failure(exc_val)
+        return False  # Don't suppress exceptions
+    
+    def protect(self, func: Callable) -> Callable:
+        """Decorator to protect a function with the circuit breaker.
+        
+        Args:
+            func: Function to protect
+        
+        Returns:
+            Wrapped function that respects circuit breaker state
+        
+        Example:
+            >>> @breaker.protect
+            ... def send_spans():
+            ...     pass
+        """
+        @wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            with self:
+                return func(*args, **kwargs)
+        return wrapper
+    
+    def reset(self) -> None:
+        """Manually reset the circuit breaker to closed state."""
+        with self._lock:
+            self._transition_to(CircuitState.CLOSED)
+            logger.info("Circuit breaker manually reset")
+    
+    def stats(self) -> dict:
+        """Get circuit breaker statistics.
+        
+        Returns:
+            Dictionary with current state and counters
+        """
+        with self._lock:
+            return {
+                "state": self._state.value,
+                "failure_count": self._failure_count,
+                "success_count": self._success_count,
+                "last_failure_time": self._last_failure_time,
+                "last_state_change": self._last_state_change,
+                "seconds_in_state": time.time() - self._last_state_change,
+            }
+
+
+# Global circuit breaker instance for the Agentreplay backend
+_default_breaker: Optional[CircuitBreaker] = None
+
+
+def get_circuit_breaker() -> CircuitBreaker:
+    """Get the default circuit breaker instance.
+    
+    Creates one if it doesn't exist with default settings.
+    
+    Returns:
+        Default CircuitBreaker instance
+    """
+    global _default_breaker
+    if _default_breaker is None:
+        _default_breaker = CircuitBreaker()
+    return _default_breaker
+
+
+def configure_circuit_breaker(
+    failure_threshold: int = 5,
+    recovery_timeout: float = 30.0,
+    success_threshold: int = 3,
+    failure_window: float = 60.0,
+) -> CircuitBreaker:
+    """Configure the default circuit breaker.
+    
+    Args:
+        failure_threshold: Number of failures before opening circuit
+        recovery_timeout: Seconds before attempting recovery
+        success_threshold: Successes needed to close circuit from half-open
+        failure_window: Time window in seconds for counting failures
+    
+    Returns:
+        Configured CircuitBreaker instance
+    """
+    global _default_breaker
+    _default_breaker = CircuitBreaker(
+        failure_threshold=failure_threshold,
+        recovery_timeout=recovery_timeout,
+        success_threshold=success_threshold,
+        failure_window=failure_window,
+    )
+    return _default_breaker