python-etcd3-async 0.1.0__py3-none-any.whl

etcd3/log.py

@@ -0,0 +1,146 @@
+"""Logging utilities for etcd3 client.
+
+This module provides logging functionality for etcd3 operations,
+including decorators for logging key operations and trace context integration.
+"""
+
+import functools
+import logging
+import os
+from contextvars import ContextVar
+from typing import Optional
+
+from etcd3.trace import get_current_span, is_tracing_available
+
+ENV_PREFIX = "ETCD_OBS_"
+ENV_LOG_LEVEL = f"{ENV_PREFIX}LOG_LEVEL"
+
+_log_operation: ContextVar[Optional[str]] = ContextVar("log_operation", default=None)
+
+_log = logging.getLogger("etcd3")
+_log.addHandler(logging.NullHandler())
+
+_env_level = os.environ.get(ENV_LOG_LEVEL)
+if _env_level:
+    try:
+        _log.setLevel(getattr(logging, _env_level.upper(), logging.DEBUG))
+    except (AttributeError, ValueError):
+        pass
+
+
+def log_operation(operation_name: str):
+    """Decorator to log operation start and completion for sync functions.
+
+    Args:
+        operation_name: Name of the operation for logging
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            _log_operation.set(operation_name)
+            if _log.isEnabledFor(logging.DEBUG):
+                _log.debug("[etcd3] Starting operation: %s", operation_name)
+            try:
+                result = func(*args, **kwargs)
+                if _log.isEnabledFor(logging.DEBUG):
+                    _log.debug("[etcd3] Completed operation: %s", operation_name)
+                return result
+            except Exception as e:
+                _log.error("[etcd3] Operation failed: %s, error: %s", operation_name, e)
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def log_operation_async(operation_name: str):
+    """Decorator to log operation start and completion for async functions.
+
+    Args:
+        operation_name: Name of the operation for logging
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            _log_operation.set(operation_name)
+            if _log.isEnabledFor(logging.DEBUG):
+                _log.debug("[etcd3] Starting operation: %s", operation_name)
+            try:
+                result = await func(*args, **kwargs)
+                if _log.isEnabledFor(logging.DEBUG):
+                    _log.debug("[etcd3] Completed operation: %s", operation_name)
+                return result
+            except Exception as e:
+                _log.error("[etcd3] Operation failed: %s, error: %s", operation_name, e)
+                raise
+
+        return wrapper
+
+    return decorator
+
+
+def get_logger(operation: Optional[str] = None) -> logging.Logger:
+    """Get the etcd3 logger instance, optionally with operation context.
+
+    Args:
+        operation: Optional operation name to set in context
+
+    Returns:
+        Logger instance
+    """
+    if operation:
+        _log_operation.set(operation)
+    return _log
+
+
+def set_log_level(level: str):
+    """Set the log level for etcd3 logger.
+
+    This can also be configured via the ETCD3_LOG_LEVEL environment variable.
+
+    Args:
+        level: Log level as string ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL')
+    """
+    _log.setLevel(getattr(logging, level.upper(), logging.DEBUG))
+
+
+def get_trace_context() -> tuple[Optional[str], Optional[str]]:
+    """Get trace context (trace_id, span_id) from current span.
+
+    Returns:
+        Tuple of (trace_id, span_id), or (None, None) if not available
+    """
+    if not is_tracing_available():
+        return None, None
+
+    span = get_current_span()
+    if span is None:
+        return None, None
+
+    trace_id = span.get_span_context().trace_id
+    span_id = span.get_span_context().span_id
+
+    trace_id_hex = format(trace_id, "032x") if trace_id else None
+    span_id_hex = format(span_id, "016x") if span_id else None
+
+    return trace_id_hex, span_id_hex
+
+
+class TraceContextLogRecord(logging.LogRecord):
+    """LogRecord subclass that includes trace context."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        trace_id, span_id = get_trace_context()
+        self.trace_id = trace_id
+        self.span_id = span_id
+        self.operation = _log_operation.get()

etcd3/log_formatters.py

@@ -0,0 +1,228 @@
+"""Logging formatters for etcd3 client.
+
+This module provides structured logging formatters including JSON and colored
+console output, with support for trace context integration.
+"""
+
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+
+class JSONFormatter(logging.Formatter):
+    """JSON structured log formatter.
+
+    Outputs logs as JSON objects with standardized fields for easy ingestion
+    into log aggregation systems like ELK, Loki, or cloud logging services.
+
+    Example output:
+        {
+            "timestamp": "2024-01-15T08:30:00.123456+00:00",
+            "level": "INFO",
+            "logger": "etcd3",
+            "message": "Completed operation: kv.put",
+            "operation": "kv.put",
+            "trace_id": "abcd1234...",
+            "span_id": "efgh5678...",
+            "source": {
+                "file": "etcd3/async_client_extensions.py",
+                "line": 177,
+                "function": "put"
+            }
+        }
+    """
+
+    def __init__(self, indent: Optional[int] = None):
+        """Initialize JSON formatter.
+
+        :param indent: Indentation for pretty-printing (None for compact)
+        """
+        super().__init__()
+        self.indent = indent
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record as JSON.
+
+        :param record: Log record to format
+        :returns: JSON string
+        """
+        # Build base log data
+        log_data: Dict[str, Any] = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+
+        # Add extra fields if present
+        if hasattr(record, "operation") and record.operation:
+            log_data["operation"] = record.operation
+
+        if hasattr(record, "trace_id") and record.trace_id:
+            log_data["trace_id"] = record.trace_id
+
+        if hasattr(record, "span_id") and record.span_id:
+            log_data["span_id"] = record.span_id
+
+        if hasattr(record, "attributes") and record.attributes:
+            log_data["attributes"] = record.attributes
+
+        # Add exception info if present
+        if record.exc_info:
+            log_data["error"] = self.formatException(record.exc_info)
+
+        # Add source location
+        log_data["source"] = {
+            "file": record.pathname,
+            "line": record.lineno,
+            "function": record.funcName,
+        }
+
+        return json.dumps(log_data, indent=self.indent, default=str)
+
+
+class ColoredTextFormatter(logging.Formatter):
+    """Colored text formatter for console output.
+
+    Adds ANSI color codes to log output for better readability in terminals.
+    Automatically detects if the output is a TTY and disables colors if not.
+    """
+
+    # ANSI color codes
+    COLORS = {
+        "DEBUG": "\033[36m",  # Cyan
+        "INFO": "\033[32m",  # Green
+        "WARNING": "\033[33m",  # Yellow
+        "ERROR": "\033[31m",  # Red
+        "CRITICAL": "\033[35m",  # Magenta
+        "RESET": "\033[0m",
+        "BOLD": "\033[1m",
+        "DIM": "\033[2m",
+    }
+
+    def __init__(self, include_trace: bool = True, fmt: Optional[str] = None):
+        """Initialize colored formatter.
+
+        :param include_trace: Whether to include trace context in output
+        :param fmt: Optional format string override
+        """
+        super().__init__()
+        self.include_trace = include_trace
+        self.supports_color = sys.stderr.isatty()
+        self.fmt = (
+            fmt
+            or "%(asctime)s %(levelcolor)s[%(levelname)s]%(reset)s %(name)s: %(message)s"
+        )
+
+    def _colorize(self, text: str, color: str) -> str:
+        """Wrap text in color codes if supported.
+
+        :param text: Text to colorize
+        :param color: Color name
+        :returns: Colorized or plain text
+        """
+        if not self.supports_color:
+            return text
+        reset = self.COLORS["RESET"]
+        color_code = self.COLORS.get(color, "")
+        return f"{color_code}{text}{reset}"
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record with colors.
+
+        :param record: Log record to format
+        :returns: Formatted string
+        """
+        # Format timestamp
+        record.asctime = self.formatTime(record)
+
+        # Build main message
+        parts = [
+            record.asctime,
+            self._colorize(f"[{record.levelname}]", record.levelname),
+            record.name,
+            ":",
+            record.getMessage(),
+        ]
+
+        # Add trace context if enabled and available
+        if self.include_trace:
+            trace_parts = []
+            if hasattr(record, "operation") and record.operation:
+                trace_parts.append(f"op={record.operation}")
+            if hasattr(record, "trace_id") and record.trace_id:
+                short_trace = record.trace_id[:16]
+                trace_parts.append(f"trace={short_trace}...")
+            if hasattr(record, "span_id") and record.span_id:
+                trace_parts.append(f"span={record.span_id[:8]}")
+
+            if trace_parts:
+                parts.append(self._colorize(f"({', '.join(trace_parts)})", "DIM"))
+
+        # Add exception
+        result = " ".join(parts)
+        if record.exc_info:
+            result += "\n" + self.formatException(record.exc_info)
+
+        return result
+
+
+class SimpleFormatter(logging.Formatter):
+    """Simple text formatter with optional components.
+
+    A more flexible version of the standard Formatter that allows
+    enabling/disabling specific fields.
+    """
+
+    def __init__(
+        self,
+        fmt: Optional[str] = None,
+        datefmt: Optional[str] = None,
+        include_source: bool = False,
+    ):
+        """Initialize simple formatter.
+
+        :param fmt: Format string
+        :param datefmt: Date format string
+        :param include_source: Whether to include source file/line
+        """
+        if fmt is None:
+            parts = ["%(asctime)s", "[%(levelname)s]", "%(name)s:", "%(message)s"]
+            if include_source:
+                parts.append("(%(pathname)s:%(lineno)d)")
+            fmt = " ".join(parts)
+
+        super().__init__(fmt=fmt, datefmt=datefmt)
+
+
+def configure_formatter(format_type: str = "text", **kwargs) -> logging.Formatter:
+    """Create a configured formatter.
+
+    Factory function to create formatters based on type.
+
+    :param format_type: Type of formatter ("text", "json", "colored")
+    :param kwargs: Additional arguments for specific formatter types
+    :returns: Configured Formatter instance
+
+    :raises ValueError: If format_type is not recognized
+
+    Example:
+        >>> formatter = configure_formatter("json", indent=2)
+        >>> handler = logging.StreamHandler()
+        >>> handler.setFormatter(formatter)
+    """
+    format_type = format_type.lower()
+
+    if format_type == "json":
+        return JSONFormatter(**kwargs)
+    elif format_type == "colored":
+        return ColoredTextFormatter(**kwargs)
+    elif format_type == "text":
+        return SimpleFormatter(**kwargs)
+    else:
+        raise ValueError(
+            f"Unknown format_type: {format_type}. "
+            "Choose from: 'text', 'json', 'colored'"
+        )

etcd3/log_sampling.py

@@ -0,0 +1,221 @@
+"""Log sampling utilities for etcd3 client.
+
+This module provides sampling strategies to control log volume in high-throughput
+scenarios, ensuring that important logs are always captured while reducing noise.
+"""
+
+import logging
+import random
+import time
+from contextvars import ContextVar
+from enum import Enum, auto
+from typing import Optional
+
+
+class SamplingStrategy(Enum):
+    """Log sampling strategies.
+
+    - ALWAYS: Always log (no sampling)
+    - RATE: Sample at a fixed rate (e.g., 10%)
+    - DYNAMIC: Adjust sampling rate based on log volume
+    - LEVEL_BASED: Different sampling by log level
+    """
+
+    ALWAYS = auto()
+    RATE = auto()
+    DYNAMIC = auto()
+    LEVEL_BASED = auto()
+
+
+class LogSampler:
+    """Log sampler with multiple strategies.
+
+    Controls log volume by sampling non-critical logs based on configured
+    strategy. Error logs are always emitted regardless of sampling.
+
+    Example:
+        >>> sampler = LogSampler(strategy=SamplingStrategy.RATE, rate=0.1)
+        >>> if sampler.should_log(logging.INFO, "kv.get"):
+        ...     logger.info("Operation completed")
+    """
+
+    def __init__(
+        self,
+        strategy: SamplingStrategy = SamplingStrategy.ALWAYS,
+        rate: float = 1.0,
+        burst: int = 100,
+        min_interval: float = 0.0,
+        level_rates: Optional[dict] = None,
+    ):
+        """Initialize log sampler.
+
+        :param strategy: Sampling strategy to use
+        :param rate: Sampling rate (0.0-1.0), 1.0 = always
+        :param burst: Maximum burst size for dynamic sampling
+        :param min_interval: Minimum interval between logs of same type (seconds)
+        :param level_rates: Per-level rates for LEVEL_BASED strategy
+        """
+        self.strategy = strategy
+        self.rate = max(0.0, min(1.0, rate))
+        self.burst = burst
+        self.min_interval = min_interval
+        self.level_rates = level_rates or {
+            logging.DEBUG: 0.1,
+            logging.INFO: 0.5,
+            logging.WARNING: 1.0,
+        }
+
+        # Context-local state for dynamic sampling
+        self._counters: ContextVar[dict] = ContextVar("sampler_counters", default={})
+        self._timestamps: ContextVar[dict] = ContextVar(
+            "sampler_timestamps", default={}
+        )
+
+    def should_log(
+        self,
+        level: int,
+        operation: Optional[str] = None,
+    ) -> bool:
+        """Determine if a log should be emitted.
+
+        :param level: Log level (from logging module)
+        :param operation: Operation identifier for per-operation sampling
+        :returns: True if log should be emitted
+        """
+        # Errors are always logged
+        if level >= logging.ERROR:
+            return True
+
+        # Apply strategy
+        if self.strategy == SamplingStrategy.ALWAYS:
+            return True
+
+        if self.strategy == SamplingStrategy.RATE:
+            return random.random() < self.rate
+
+        if self.strategy == SamplingStrategy.LEVEL_BASED:
+            level_rate = self.level_rates.get(level, 1.0)
+            return random.random() < level_rate
+
+        if self.strategy == SamplingStrategy.DYNAMIC:
+            return self._dynamic_sample(operation)
+
+        return True
+
+    def _dynamic_sample(self, operation: Optional[str]) -> bool:
+        """Dynamic sampling based on token bucket algorithm.
+
+        :param operation: Operation identifier
+        :returns: True if should log
+        """
+        key = operation or "default"
+        current_time = time.time()
+
+        # Check minimum interval
+        if self.min_interval > 0:
+            timestamps = self._timestamps.get()
+            last_time = timestamps.get(key, 0)
+            if current_time - last_time < self.min_interval:
+                return False
+
+        # Token bucket: allow burst, then sample
+        counters = self._counters.get()
+        count = counters.get(key, 0)
+
+        if count < self.burst:
+            # Within burst allowance
+            counters[key] = count + 1
+            timestamps = self._timestamps.get()
+            timestamps[key] = current_time
+            return True
+
+        # Beyond burst, sample at rate
+        if random.random() < self.rate:
+            timestamps = self._timestamps.get()
+            timestamps[key] = current_time
+            return True
+
+        return False
+
+    def reset(self):
+        """Reset sampler state.
+
+        Clears all counters and timestamps. Useful for testing or when
+        log volume characteristics change significantly.
+        """
+        self._counters.set({})
+        self._timestamps.set({})
+
+
+# Global sampler instance
+_default_sampler: Optional[LogSampler] = None
+
+
+def get_sampler() -> LogSampler:
+    """Get the global log sampler instance.
+
+    Creates a default sampler if none exists.
+
+    :returns: Global LogSampler instance
+    """
+    global _default_sampler
+    if _default_sampler is None:
+        _default_sampler = LogSampler()
+    return _default_sampler
+
+
+def set_sampler(sampler: LogSampler):
+    """Set the global log sampler instance.
+
+    :param sampler: LogSampler instance to use globally
+
+    Example:
+        >>> new_sampler = LogSampler(strategy=SamplingStrategy.RATE, rate=0.5)
+        >>> set_sampler(new_sampler)
+    """
+    global _default_sampler
+    _default_sampler = sampler
+
+
+def should_log(
+    level: int,
+    operation: Optional[str] = None,
+) -> bool:
+    """Convenience function to check if should log using global sampler.
+
+    :param level: Log level
+    :param operation: Operation identifier
+    :returns: True if should log
+    """
+    return get_sampler().should_log(level, operation)
+
+
+def configure_from_env() -> LogSampler:
+    """Configure sampler from environment variables.
+
+    Environment variables (unified with ETCD_OBS_ prefix):
+    - ETCD_OBS_LOG_SAMPLE_STRATEGY: "always", "rate", "dynamic", "level_based"
+    - ETCD_OBS_LOG_SAMPLE_RATE: Float between 0.0 and 1.0
+    - ETCD_OBS_LOG_SAMPLE_BURST: Integer burst size for dynamic sampling
+
+    :returns: Configured LogSampler
+    """
+    import os
+
+    ENV_PREFIX = "ETCD_OBS_"
+
+    strategy_str = os.environ.get(f"{ENV_PREFIX}LOG_SAMPLE_STRATEGY", "always").upper()
+    strategy_map = {
+        "ALWAYS": SamplingStrategy.ALWAYS,
+        "RATE": SamplingStrategy.RATE,
+        "DYNAMIC": SamplingStrategy.DYNAMIC,
+        "LEVEL_BASED": SamplingStrategy.LEVEL_BASED,
+    }
+    strategy = strategy_map.get(strategy_str, SamplingStrategy.ALWAYS)
+
+    rate = float(os.environ.get(f"{ENV_PREFIX}LOG_SAMPLE_RATE", "1.0"))
+    burst = int(os.environ.get(f"{ENV_PREFIX}LOG_SAMPLE_BURST", "100"))
+
+    sampler = LogSampler(strategy=strategy, rate=rate, burst=burst)
+    set_sampler(sampler)
+    return sampler

etcd3/members.py

@@ -0,0 +1,44 @@
+class Member(object):
+    """
+    A member of the etcd cluster.
+
+    :ivar id: ID of the member
+    :ivar name: human-readable name of the member
+    :ivar peer_urls: list of URLs the member exposes to the cluster for
+                     communication
+    :ivar client_urls: list of URLs the member exposes to clients for
+                       communication
+    """
+
+    def __init__(self, id, name, peer_urls, client_urls, etcd_client=None):
+        self.id = id
+        self.name = name
+        self.peer_urls = peer_urls
+        self.client_urls = client_urls
+        self._etcd_client = etcd_client
+
+    def __str__(self):
+        return "Member {id}: peer urls: {peer_urls}, client urls: {client_urls}".format(
+            id=self.id, peer_urls=self.peer_urls, client_urls=self.client_urls
+        )
+
+    def remove(self):
+        """Remove this member from the cluster."""
+        self._etcd_client.remove_member(self.id)
+
+    def update(self, peer_urls):
+        """
+        Update the configuration of this member.
+
+        :param peer_urls: new list of peer urls the member will use to
+                          communicate with the cluster
+        """
+        self._etcd_client.update_member(self.id, peer_urls)
+
+    @property
+    def active_alarms(self):
+        """Get active alarms of the member.
+
+        :returns: Alarms
+        """
+        return self._etcd_client.list_alarms(member_id=self.id)