taipanstack 0.1.0__py3-none-any.whl

taipanstack/utils/logging.py

@@ -0,0 +1,328 @@
+"""
+Structured logging with context.
+
+Provides a configured logger with support for structured output,
+context propagation, and proper formatting.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+try:
+    import structlog
+
+    HAS_STRUCTLOG = True
+except ImportError:
+    HAS_STRUCTLOG = False
+
+
+# Default log format
+DEFAULT_FORMAT = "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
+JSON_FORMAT = (
+    '{"timestamp": "%(asctime)s", "level": "%(levelname)s", '
+    '"logger": "%(name)s", "message": "%(message)s"}'
+)
+
+
+class StackLogger:
+    """Enhanced logger with context support.
+
+    Provides a wrapper around standard logging with additional features
+    like context propagation and structured output support.
+
+    Attributes:
+        name: Logger name.
+        level: Current log level.
+
+    """
+
+    def __init__(
+        self,
+        name: str = "stack",
+        level: str = "INFO",
+        *,
+        use_structured: bool = False,
+    ) -> None:
+        """Initialize the logger.
+
+        Args:
+            name: Logger name.
+            level: Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+            use_structured: Use structured logging if structlog is available.
+
+        """
+        self.name = name
+        self.level = level
+        self._context: dict[str, Any] = {}
+
+        if use_structured and HAS_STRUCTLOG:
+            self._logger = structlog.get_logger(name)
+            self._structured = True
+        else:
+            self._logger = logging.getLogger(name)
+            self._logger.setLevel(getattr(logging, level.upper()))
+            self._structured = False
+
+    def bind(self, **context: Any) -> StackLogger:
+        """Add context to logger.
+
+        Args:
+            **context: Key-value pairs to add to context.
+
+        Returns:
+            Self for chaining.
+
+        """
+        self._context.update(context)
+        if self._structured and HAS_STRUCTLOG:
+            self._logger = self._logger.bind(**context)
+        return self
+
+    def unbind(self, *keys: str) -> StackLogger:
+        """Remove context keys.
+
+        Args:
+            *keys: Keys to remove from context.
+
+        Returns:
+            Self for chaining.
+
+        """
+        for key in keys:
+            self._context.pop(key, None)
+        if self._structured and HAS_STRUCTLOG:
+            self._logger = self._logger.unbind(*keys)
+        return self
+
+    def _format_message(self, message: str, **kwargs: Any) -> str:
+        """Format message with context.
+
+        Args:
+            message: The log message.
+            **kwargs: Additional context for this message.
+
+        Returns:
+            Formatted message string.
+
+        """
+        if not kwargs and not self._context:
+            return message
+
+        context = {**self._context, **kwargs}
+        context_str = " ".join(f"{k}={v}" for k, v in context.items())
+        return f"{message} | {context_str}"
+
+    def debug(self, message: str, **kwargs: Any) -> None:
+        """Log a debug message.
+
+        Args:
+            message: The message to log.
+            **kwargs: Additional context.
+
+        """
+        if self._structured:
+            self._logger.debug(message, **kwargs)
+        else:
+            self._logger.debug(self._format_message(message, **kwargs))
+
+    def info(self, message: str, **kwargs: Any) -> None:
+        """Log an info message.
+
+        Args:
+            message: The message to log.
+            **kwargs: Additional context.
+
+        """
+        if self._structured:
+            self._logger.info(message, **kwargs)
+        else:
+            self._logger.info(self._format_message(message, **kwargs))
+
+    def warning(self, message: str, **kwargs: Any) -> None:
+        """Log a warning message.
+
+        Args:
+            message: The message to log.
+            **kwargs: Additional context.
+
+        """
+        if self._structured:
+            self._logger.warning(message, **kwargs)
+        else:
+            self._logger.warning(self._format_message(message, **kwargs))
+
+    def error(self, message: str, **kwargs: Any) -> None:
+        """Log an error message.
+
+        Args:
+            message: The message to log.
+            **kwargs: Additional context.
+
+        """
+        if self._structured:
+            self._logger.error(message, **kwargs)
+        else:
+            self._logger.error(self._format_message(message, **kwargs))
+
+    def critical(self, message: str, **kwargs: Any) -> None:
+        """Log a critical message.
+
+        Args:
+            message: The message to log.
+            **kwargs: Additional context.
+
+        """
+        if self._structured:
+            self._logger.critical(message, **kwargs)
+        else:
+            self._logger.critical(self._format_message(message, **kwargs))
+
+    def exception(self, message: str, **kwargs: Any) -> None:
+        """Log an exception with traceback.
+
+        Args:
+            message: The message to log.
+            **kwargs: Additional context.
+
+        """
+        if self._structured:
+            self._logger.exception(message, **kwargs)
+        else:
+            self._logger.exception(self._format_message(message, **kwargs))
+
+
+def setup_logging(
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO",
+    *,
+    format_type: Literal["simple", "detailed", "json"] = "detailed",
+    log_file: str | None = None,
+    use_structured: bool = False,
+) -> None:
+    """Configure the root logger.
+
+    Args:
+        level: Log level to set.
+        format_type: Output format type.
+        log_file: Optional file to log to.
+        use_structured: Use structlog if available.
+
+    """
+    # Configure structlog if available and requested
+    if use_structured and HAS_STRUCTLOG:
+        structlog.configure(
+            processors=[
+                structlog.stdlib.filter_by_level,
+                structlog.stdlib.add_logger_name,
+                structlog.stdlib.add_log_level,
+                structlog.processors.TimeStamper(fmt="iso"),
+                structlog.processors.StackInfoRenderer(),
+                structlog.processors.format_exc_info,
+                structlog.processors.UnicodeDecoder(),
+                structlog.processors.JSONRenderer(),
+            ],
+            wrapper_class=structlog.stdlib.BoundLogger,
+            context_class=dict,
+            logger_factory=structlog.stdlib.LoggerFactory(),
+        )
+        return
+
+    # Standard logging configuration
+    if format_type == "simple":
+        log_format = "%(levelname)s: %(message)s"
+    elif format_type == "json":
+        log_format = JSON_FORMAT
+    else:
+        log_format = DEFAULT_FORMAT
+
+    handlers: list[logging.Handler] = [logging.StreamHandler(sys.stdout)]
+
+    if log_file:
+        handlers.append(logging.FileHandler(log_file, encoding="utf-8"))
+
+    logging.basicConfig(
+        level=getattr(logging, level.upper()),
+        format=log_format,
+        handlers=handlers,
+        force=True,
+    )
+
+
+def get_logger(
+    name: str = "stack",
+    *,
+    level: str = "INFO",
+    use_structured: bool = False,
+) -> StackLogger:
+    """Get a configured logger instance.
+
+    Args:
+        name: Logger name.
+        level: Log level.
+        use_structured: Use structlog if available.
+
+    Returns:
+        Configured StackLogger instance.
+
+    Example:
+        >>> logger = get_logger("my_module")
+        >>> logger.bind(request_id="123").info("Processing request")
+
+    """
+    return StackLogger(name, level, use_structured=use_structured)
+
+
+def log_operation(
+    operation: str,
+    *,
+    logger: StackLogger | None = None,
+    level: str = "INFO",
+) -> Any:
+    """Context manager for logging operations.
+
+    Args:
+        operation: Name of the operation.
+        logger: Logger to use (creates one if not provided).
+        level: Log level for messages.
+
+    Yields:
+        The logger instance.
+
+    Example:
+        >>> with log_operation("setup") as logger:
+        ...     logger.info("Setting up environment")
+
+    """
+
+    @contextmanager
+    def _log_context() -> Any:
+        nonlocal logger
+        if logger is None:
+            logger = get_logger()
+
+        start_time = datetime.now(UTC)
+        logger.bind(operation=operation)
+
+        log_method = getattr(logger, level.lower())
+        log_method(f"Starting: {operation}")
+
+        try:
+            yield logger
+            duration = (datetime.now(UTC) - start_time).total_seconds()
+            log_method(f"Completed: {operation}", duration_seconds=duration)
+        except Exception as e:
+            duration = (datetime.now(UTC) - start_time).total_seconds()
+            logger.exception(
+                f"Failed: {operation}",
+                duration_seconds=duration,
+                error=str(e),
+            )
+            raise
+        finally:
+            logger.unbind("operation")
+
+    return _log_context()

taipanstack/utils/metrics.py

@@ -0,0 +1,272 @@
+"""
+Metrics collection and monitoring utilities.
+
+Provides lightweight metrics collection for monitoring
+application performance and health. Compatible with any
+Python framework.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import threading
+import time
+from collections import defaultdict
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+logger = logging.getLogger("taipanstack.utils.metrics")
+
+
+@dataclass
+class TimingStats:
+    """Statistics for timing measurements."""
+
+    count: int = 0
+    total_time: float = 0.0
+    min_time: float = float("inf")
+    max_time: float = 0.0
+
+    @property
+    def avg_time(self) -> float:
+        """Calculate average time."""
+        return self.total_time / self.count if self.count > 0 else 0.0
+
+    def record(self, duration: float) -> None:
+        """Record a timing measurement."""
+        self.count += 1
+        self.total_time += duration
+        self.min_time = min(self.min_time, duration)
+        self.max_time = max(self.max_time, duration)
+
+
+@dataclass
+class Counter:
+    """Simple counter metric."""
+
+    value: int = 0
+    lock: threading.Lock = field(default_factory=threading.Lock)
+
+    def increment(self, amount: int = 1) -> int:
+        """Increment counter and return new value."""
+        with self.lock:
+            self.value += amount
+            return self.value
+
+    def decrement(self, amount: int = 1) -> int:
+        """Decrement counter and return new value."""
+        with self.lock:
+            self.value -= amount
+            return self.value
+
+    def reset(self) -> None:
+        """Reset counter to zero."""
+        with self.lock:
+            self.value = 0
+
+
+class MetricsCollector:
+    """Centralized metrics collection.
+
+    Thread-safe collector for various metric types including
+    counters, timers, and gauges.
+
+    Example:
+        >>> metrics = MetricsCollector()
+        >>> metrics.increment("requests_total")
+        >>> with metrics.timer("request_duration"):
+        ...     process_request()
+
+    """
+
+    _instance: MetricsCollector | None = None
+    _lock = threading.Lock()
+    _initialized: bool
+
+    def __new__(cls) -> MetricsCollector:
+        """Singleton pattern for global metrics access."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self) -> None:
+        """Initialize metrics collector."""
+        if self._initialized:
+            return
+
+        self._counters: dict[str, Counter] = defaultdict(Counter)
+        self._timers: dict[str, TimingStats] = defaultdict(TimingStats)
+        self._gauges: dict[str, float] = {}
+        self._data_lock = threading.Lock()
+        self._initialized = True
+
+    def increment(self, name: str, amount: int = 1) -> int:
+        """Increment a counter metric."""
+        return self._counters[name].increment(amount)
+
+    def decrement(self, name: str, amount: int = 1) -> int:
+        """Decrement a counter metric."""
+        return self._counters[name].decrement(amount)
+
+    def gauge(self, name: str, value: float) -> None:
+        """Set a gauge metric value."""
+        with self._data_lock:
+            self._gauges[name] = value
+
+    def get_gauge(self, name: str) -> float | None:
+        """Get a gauge metric value."""
+        with self._data_lock:
+            return self._gauges.get(name)
+
+    def record_time(self, name: str, duration: float) -> None:
+        """Record a timing measurement."""
+        self._timers[name].record(duration)
+
+    def timer(self, name: str) -> Timer:
+        """Create a context manager timer."""
+        return Timer(name, self)
+
+    def get_counter(self, name: str) -> int:
+        """Get current counter value."""
+        return self._counters[name].value
+
+    def get_timer_stats(self, name: str) -> TimingStats | None:
+        """Get timing statistics for a named timer."""
+        return self._timers.get(name)
+
+    def get_all_metrics(self) -> dict[str, Any]:
+        """Get all metrics as a dictionary."""
+        with self._data_lock:
+            return {
+                "counters": {k: v.value for k, v in self._counters.items()},
+                "timers": {
+                    k: {
+                        "count": v.count,
+                        "avg": v.avg_time,
+                        "min": v.min_time if v.count > 0 else 0,
+                        "max": v.max_time,
+                        "total": v.total_time,
+                    }
+                    for k, v in self._timers.items()
+                },
+                "gauges": dict(self._gauges),
+            }
+
+    def reset(self) -> None:
+        """Reset all metrics."""
+        with self._data_lock:
+            self._counters.clear()
+            self._timers.clear()
+            self._gauges.clear()
+
+
+class Timer:
+    """Context manager for timing code blocks."""
+
+    def __init__(self, name: str, collector: MetricsCollector) -> None:
+        """Initialize timer.
+
+        Args:
+            name: Name of the timer metric.
+            collector: MetricsCollector to record to.
+
+        """
+        self.name = name
+        self.collector = collector
+        self.start_time: float = 0.0
+
+    def __enter__(self) -> Timer:
+        """Start the timer."""
+        self.start_time = time.perf_counter()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Stop timer and record duration."""
+        duration = time.perf_counter() - self.start_time
+        self.collector.record_time(self.name, duration)
+
+
+def timed(
+    name: str | None = None,
+    *,
+    collector: MetricsCollector | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Decorator to time function execution.
+
+    Args:
+        name: Optional metric name (defaults to function name).
+        collector: Optional MetricsCollector instance.
+
+    Returns:
+        Decorated function that records execution time.
+
+    Example:
+        >>> @timed("api_call_duration")
+        ... def call_api(endpoint: str) -> dict:
+        ...     return requests.get(endpoint).json()
+
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        metric_name = name or func.__name__
+        metrics = collector or MetricsCollector()
+
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            start = time.perf_counter()
+            try:
+                return func(*args, **kwargs)
+            finally:
+                duration = time.perf_counter() - start
+                metrics.record_time(metric_name, duration)
+
+        return wrapper
+
+    return decorator
+
+
+def counted(
+    name: str | None = None,
+    *,
+    collector: MetricsCollector | None = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Decorator to count function calls.
+
+    Args:
+        name: Optional metric name (defaults to function name).
+        collector: Optional MetricsCollector instance.
+
+    Returns:
+        Decorated function that counts calls.
+
+    Example:
+        >>> @counted("login_attempts")
+        ... def login(username: str, password: str) -> bool:
+        ...     return authenticate(username, password)
+
+    """
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        metric_name = name or f"{func.__name__}_calls"
+        metrics = collector or MetricsCollector()
+
+        @functools.wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            metrics.increment(metric_name)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+# Global metrics instance
+metrics = MetricsCollector()