PECLibrary 0.7.0__py3-none-any.whl

PECLibrary/config/__init__.py

@@ -0,0 +1,14 @@
+"""
+Configuration module for palantir-event-capture
+"""
+
+from .settings import Settings, get_settings, configure, reset_settings
+from . import defaults
+
+__all__ = [
+    "Settings", 
+    "get_settings", 
+    "configure", 
+    "reset_settings", 
+    "defaults"
+]

PECLibrary/config/defaults.py

@@ -0,0 +1,59 @@
+"""
+Default configuration values for palantir-event-capture
+"""
+
+from ..models.captured_models import Severity, EventType, PipelineComponent
+
+# Kafka Configuration
+DEFAULT_KAFKA_BOOTSTRAP_SERVERS_RCA = "kafka01.prod.bt:9092,kafka02.prod.bt:9092,kafka03.prod.bt:9092,kafka04.prod.bt:9092"
+DEFAULT_KAFKA_EVENT_TOPIC_RCA = "rca.events"
+DEFAULT_KAFKA_ENABLED_RCA = True  # Disabled by default to avoid connection errors
+DEFAULT_KAFKA_COMPRESSION_RCA = "gzip"
+DEFAULT_KAFKA_BATCH_SIZE_RCA = 16384
+DEFAULT_KAFKA_LINGER_MS_RCA = 10
+
+# Logging Configuration
+DEFAULT_LOG_LEVEL = "INFO"
+DEFAULT_LOG_TO_CONSOLE = True
+DEFAULT_LOG_FORMAT = (
+    "<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
+    "<level>{level: <8}</level> | "
+    "<cyan>{name}</cyan>:<cyan>{function}</cyan> - "
+    "<level>{message}</level>"
+)
+
+# Event Capture Settings
+DEFAULT_SEND_TO_TRANSPORT = True
+DEFAULT_COMPONENT = PipelineComponent.UNKNOWN
+DEFAULT_SEVERITY = Severity.MEDIUM
+DEFAULT_EVENT_TYPE = EventType.ERROR
+DEFAULT_RERAISE = True
+DEFAULT_ENABLE_STACK_TRACES = True
+DEFAULT_MAX_STACK_TRACE_LENGTH = 5000  # characters
+DEFAULT_USE_BACKGROUND_TRANSPORT = False
+
+# Retry Configuration
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_DELAY = 1.0  # seconds
+DEFAULT_RETRY_BACKOFF = 2.0  # multiplier
+DEFAULT_CAPTURE_ALL_RETRIES = False  # Only capture final failure by default
+
+# Performance Settings
+DEFAULT_ASYNC_TRANSPORT = False
+DEFAULT_EVENT_BATCH_SIZE = 100
+DEFAULT_EVENT_QUEUE_SIZE = 1000
+
+# Storage Configuration (optional)
+DEFAULT_STORAGE_ENABLED = False
+DEFAULT_STORAGE_PATH = "./event_logs"
+DEFAULT_STORAGE_MAX_FILES = 100
+DEFAULT_STORAGE_MAX_FILE_SIZE_MB = 10
+
+# Security & Privacy
+DEFAULT_SANITIZE_STACK_TRACES = False
+DEFAULT_PII_PATTERNS = []  # Regex patterns to redact
+DEFAULT_MAX_METADATA_SIZE = 10000  # characters
+
+# Event Registry
+DEFAULT_ID_REGISTRY_CLEANUP_INTERVAL = 3600  # seconds
+DEFAULT_ID_REGISTRY_MAX_SIZE = 100000  # events

PECLibrary/config/settings.py

@@ -0,0 +1,178 @@
+"""
+Configuration management for palantir-event-capture
+"""
+
+import os
+from typing import Any, Dict, Optional
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from . import defaults
+from ..models.captured_models import Severity, EventType, PipelineComponent
+
+
+class Settings:
+    """Global settings manager"""
+
+    def __init__(self):
+        # Load environment variables from .env file if it exists
+        load_dotenv()
+
+        # Kafka Configuration
+        self.KAFKA_BOOTSTRAP_SERVERS_RCA: str = self._get_env(
+            "KAFKA_BOOTSTRAP_SERVERS_RCA", defaults.DEFAULT_KAFKA_BOOTSTRAP_SERVERS_RCA
+        )
+        self.KAFKA_EVENT_TOPIC_RCA: str = self._get_env(
+            "KAFKA_EVENT_TOPIC_RCA", defaults.DEFAULT_KAFKA_EVENT_TOPIC_RCA
+        )
+        self.KAFKA_ENABLED_RCA: bool = self._get_env_bool(
+            "KAFKA_ENABLED_RCA", defaults.DEFAULT_KAFKA_ENABLED_RCA
+        )
+        self.KAFKA_COMPRESSION_RCA: str = self._get_env(
+            "KAFKA_COMPRESSION_RCA", defaults.DEFAULT_KAFKA_COMPRESSION_RCA
+        )
+        self.KAFKA_BATCH_SIZE_RCA: int = self._get_env_int(
+            "KAFKA_BATCH_SIZE_RCA", defaults.DEFAULT_KAFKA_BATCH_SIZE_RCA
+        )
+        self.KAFKA_LINGER_MS_RCA: int = self._get_env_int(
+            "KAFKA_LINGER_MS_RCA", defaults.DEFAULT_KAFKA_LINGER_MS_RCA
+        )
+
+        # Logging Configuration
+        self.log_level: str = self._get_env("LOG_LEVEL", defaults.DEFAULT_LOG_LEVEL)
+        self.log_to_console: bool = self._get_env_bool(
+            "LOG_TO_CONSOLE", defaults.DEFAULT_LOG_TO_CONSOLE
+        )
+        self.log_format: str = self._get_env("LOG_FORMAT", defaults.DEFAULT_LOG_FORMAT)
+
+        # Event Capture Settings
+        self.send_to_transport: bool = self._get_env_bool(
+            "SEND_TO_TRANSPORT", defaults.DEFAULT_SEND_TO_TRANSPORT
+        )
+        self.default_component: PipelineComponent = self._get_env_enum(
+            "DEFAULT_COMPONENT", PipelineComponent, defaults.DEFAULT_COMPONENT
+        )
+        self.default_severity: Severity = self._get_env_enum(
+            "DEFAULT_SEVERITY", Severity, defaults.DEFAULT_SEVERITY
+        )
+        self.default_reraise: bool = self._get_env_bool(
+            "DEFAULT_RERAISE", defaults.DEFAULT_RERAISE
+        )
+        self.enable_stack_traces: bool = self._get_env_bool(
+            "ENABLE_STACK_TRACES", defaults.DEFAULT_ENABLE_STACK_TRACES
+        )
+        self.max_stack_trace_length: int = self._get_env_int(
+            "MAX_STACK_TRACE_LENGTH", defaults.DEFAULT_MAX_STACK_TRACE_LENGTH
+        )
+        
+        self.use_background_transport: bool = self._get_env_bool(
+            "USE_BACKGROUND_TRANSPORT", False  # Default to False for easier debugging
+        )
+
+        # Retry Configuration
+        self.default_max_retries: int = self._get_env_int(
+            "DEFAULT_MAX_RETRIES", defaults.DEFAULT_MAX_RETRIES
+        )
+        self.default_retry_delay: float = self._get_env_float(
+            "DEFAULT_RETRY_DELAY", defaults.DEFAULT_RETRY_DELAY
+        )
+        self.default_retry_backoff: float = self._get_env_float(
+            "DEFAULT_RETRY_BACKOFF", defaults.DEFAULT_RETRY_BACKOFF
+        )
+
+        # Storage Configuration
+        self.storage_enabled: bool = self._get_env_bool(
+            "STORAGE_ENABLED", defaults.DEFAULT_STORAGE_ENABLED
+        )
+        self.storage_path: Path = Path(
+            self._get_env("STORAGE_PATH", defaults.DEFAULT_STORAGE_PATH)
+        )
+
+    def _get_env(self, key: str, default: Any) -> Any:
+        """Get environment variable or return default"""
+        return os.getenv(key, default)
+
+    def _get_env_bool(self, key: str, default: bool) -> bool:
+        """Get boolean environment variable"""
+        value = os.getenv(key)
+        if value is None:
+            return default
+        return value.lower() in ("true", "1", "yes", "on")
+
+    def _get_env_int(self, key: str, default: int) -> int:
+        """Get integer environment variable"""
+        value = os.getenv(key)
+        if value is None:
+            return default
+        try:
+            return int(value)
+        except ValueError:
+            return default
+
+    def _get_env_float(self, key: str, default: float) -> float:
+        """Get float environment variable"""
+        value = os.getenv(key)
+        if value is None:
+            return default
+        try:
+            return float(value)
+        except ValueError:
+            return default
+
+    def _get_env_enum(self, key: str, enum_class: type, default: Any) -> Any:
+        """Get enum environment variable"""
+        value = os.getenv(key)
+        if value is None:
+            return default
+        try:
+            return enum_class(value.lower())
+        except (ValueError, KeyError):
+            return default
+
+    def update(self, **kwargs: Any) -> None:
+        """Update settings programmatically"""
+        for key, value in kwargs.items():
+            if hasattr(self, key):
+                setattr(self, key, value)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert settings to dictionary"""
+        return {
+            key: value
+            for key, value in self.__dict__.items()
+            if not key.startswith("_")
+        }
+
+
+# Global settings instance
+_settings: Optional[Settings] = None
+
+
+def get_settings() -> Settings:
+    """Get or create global settings instance"""
+    global _settings
+    if _settings is None:
+        _settings = Settings()
+    return _settings
+
+
+def configure(**kwargs: Any) -> None:
+    """
+    Configure settings programmatically.
+
+    Example:
+        configure(
+            KAFKA_BOOTSTRAP_SERVERS_RCA="localhost:9092",
+            KAFKA_ENABLED_RCA=True,
+            log_level="DEBUG"
+        )
+    """
+    settings = get_settings()
+    settings.update(**kwargs)
+
+
+def reset_settings() -> None:
+    """Reset settings to defaults (useful for testing)"""
+    global _settings
+    _settings = None

PECLibrary/decorators/__init__.py

@@ -0,0 +1,17 @@
+"""
+Decorators module for palantir-event-capture
+"""
+
+from .capture import (
+    capture_errors,
+    async_capture_errors,
+    retry_with_capture,
+    capture_method_errors,
+)
+
+__all__ = [
+    "capture_errors",
+    "async_capture_errors",
+    "retry_with_capture",
+    "capture_method_errors",
+]

PECLibrary/decorators/capture.py

@@ -0,0 +1,279 @@
+"""
+Decorators for automatic error capture.
+"""
+
+import functools
+import asyncio
+import time
+from typing import Callable, Optional, Any, TypeVar, ParamSpec
+
+from ..models.captured_models import CaptureConfig, PipelineComponent, Severity, EventType
+from ..services.error_capture import get_capture_service
+from ..utils.logger_config import get_logger
+
+logger = get_logger()
+
+P = ParamSpec('P')
+T = TypeVar('T')
+
+
+def capture_errors(
+    component: Optional[PipelineComponent] = None,
+    component_name: Optional[str] = None,
+    pipeline_name: Optional[str] = None,
+    engine_name: Optional[str] = None,
+    severity: Severity = Severity.HIGH,
+    event_type: EventType = EventType.ERROR,
+    reraise: bool = True,
+    log_to_console: bool = True,
+    send_to_transport: bool = True,
+    **metadata: Any,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """
+    Decorator to automatically capture exceptions in functions.
+    
+    Args:
+        reraise: If True, re-raise the exception after capturing.
+                 If False, swallow the exception and return None.
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            config = CaptureConfig(
+                component=component,
+                component_name=component_name,
+                pipeline_name=pipeline_name,
+                engine_name=engine_name,
+                severity=severity,
+                event_type=event_type,
+                reraise=False,
+                log_to_console=log_to_console,
+                send_to_transport=send_to_transport,
+                metadata={
+                    'function': func.__name__,
+                    'module': func.__module__,
+                    **metadata,
+                },
+            )
+
+            try:
+                return func(*args, **kwargs)
+            except Exception as e:
+                logger.debug(f"[DECORATOR] ❌ Caught {type(e).__name__}: {e}")
+                
+                service = get_capture_service()
+                
+                # Capture the error (won't reraise because config.reraise=False)
+                try:
+                    event = service.capture_exception(
+                        e, 
+                        config=config, 
+                        skip_frames=1,
+                        async_send=True
+                    )
+                    
+                    if event:
+                        logger.info(f"[DECORATOR] ✅ Event {event.id} captured and sent")
+                    else:
+                        logger.warning(f"[DECORATOR] ⚠️ Event capture returned None")
+                        
+                except Exception as capture_error:
+                    logger.error(f"[DECORATOR] ❌ Capture failed: {capture_error}")
+                    # Continue to reraise check below
+                
+                if reraise:
+                    logger.debug(f"[DECORATOR] Re-raising {type(e).__name__}")
+                    raise
+                else:
+                    logger.debug(f"[DECORATOR] Swallowing error, returning None")
+                    return None  # Swallow error, return None
+
+        return wrapper 
+
+    return decorator
+
+
+def async_capture_errors(
+    component: Optional[PipelineComponent] = None,
+    component_name: Optional[str] = None,
+    pipeline_name: Optional[str] = None,
+    engine_name: Optional[str] = None,
+    severity: Severity = Severity.HIGH,
+    event_type: EventType = EventType.ERROR,
+    reraise: bool = True,
+    log_to_console: bool = True,
+    send_to_transport: bool = True,
+    **metadata: Any,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """
+    Async decorator to automatically capture exceptions in async functions.
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        @functools.wraps(func)
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            config = CaptureConfig(
+                component=component,
+                component_name=component_name,
+                pipeline_name=pipeline_name,
+                engine_name=engine_name,
+                severity=severity,
+                event_type=event_type,
+                reraise=False,
+                log_to_console=log_to_console,
+                send_to_transport=send_to_transport,
+                metadata={
+                    'function': func.__name__,
+                    'module': func.__module__,
+                    **metadata,
+                },
+            )
+
+            try:
+                return await func(*args, **kwargs)
+            except Exception as e:
+                logger.debug(f"[ASYNC DECORATOR] ❌ Caught {type(e).__name__}: {e}")
+                
+                service = get_capture_service()
+                
+                try:
+                    event = service.capture_exception(
+                        e, 
+                        config=config, 
+                        skip_frames=1,
+                        async_send=True
+                    )
+                    
+                    if event:
+                        logger.info(f"[ASYNC DECORATOR] ✅ Event {event.id} captured")
+                    else:
+                        logger.warning(f"[ASYNC DECORATOR] ⚠️ Event capture returned None")
+                        
+                except Exception as capture_error:
+                    logger.error(f"[ASYNC DECORATOR] ❌ Capture failed: {capture_error}")
+                
+                # Handle reraise
+                if reraise:
+                    logger.debug(f"[ASYNC DECORATOR] Re-raising {type(e).__name__}")
+                    raise
+                else:
+                    logger.debug(f"[ASYNC DECORATOR] Swallowing error, returning None")
+                    return None
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def retry_with_capture(
+    max_retries: int = 3,
+    delay: float = 1.0,
+    backoff: float = 2.0,
+    component: Optional[PipelineComponent] = None,
+    component_name: Optional[str] = None,
+    pipeline_name: Optional[str] = None,
+    engine_name: Optional[str] = None,
+    severity: Severity = Severity.MEDIUM,
+    capture_all_attempts: bool = False,
+    **metadata: Any,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """
+    Decorator that retries a function on failure and captures errors.
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            last_exception: Optional[Exception] = None
+            current_delay = delay
+
+            for attempt in range(max_retries + 1):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    last_exception = e
+
+                    # Determine if this is the final attempt
+                    is_final = attempt == max_retries
+
+                    # Capture this attempt if configured
+                    if capture_all_attempts or is_final:
+                        config = CaptureConfig(
+                            component=component,
+                            component_name=component_name,
+                            pipeline_name=pipeline_name,
+                            engine_name=engine_name,
+                            severity=severity if not is_final else Severity.HIGH,
+                            event_type=EventType.ERROR if is_final else EventType.WARNING,
+                            reraise=False,  # Never reraise in capture_exception
+                            log_to_console=True,
+                            send_to_transport=is_final,  # Only send final failure
+                            metadata={
+                                'function': func.__name__,
+                                'module': func.__module__,
+                                'attempt': attempt + 1,
+                                'max_retries': max_retries,
+                                'is_final_attempt': is_final,
+                                **metadata,
+                            },
+                        )
+                        service = get_capture_service()
+                        try:
+                            service.capture_exception(e, config=config, skip_frames=1, async_send=True)
+                        except Exception:
+                            pass  # Ignore exceptions during capture
+
+                    # Sleep before retry (except on last attempt)
+                    if not is_final:
+                        time.sleep(current_delay)
+                        current_delay *= backoff
+
+            # Raise the last exception after all retries
+            if last_exception:
+                raise last_exception
+
+            # Should never reach here
+            raise RuntimeError("Unexpected state in retry_with_capture")
+
+        return wrapper  # type: ignore
+
+    return decorator
+
+
+def capture_method_errors(
+    component: Optional[PipelineComponent] = None,
+    severity: Severity = Severity.HIGH,
+    reraise: bool = True,
+) -> Callable[[type], type]:
+    """
+    Class decorator to wrap all methods with error capture.
+    """
+
+    def decorator(cls: type) -> type:
+        for attr_name in dir(cls):
+            if attr_name.startswith('_'):
+                continue
+
+            attr = getattr(cls, attr_name)
+            if callable(attr):
+                # Check if it's an async method
+                if asyncio.iscoroutinefunction(attr):
+                    wrapped = async_capture_errors(
+                        component=component,
+                        component_name=cls.__name__,
+                        severity=severity,
+                        reraise=reraise,
+                    )(attr)
+                else:
+                    wrapped = capture_errors(
+                        component=component,
+                        component_name=cls.__name__,
+                        severity=severity,
+                        reraise=reraise,
+                    )(attr)
+                setattr(cls, attr_name, wrapped)
+
+        return cls
+
+    return decorator