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

etcd3/observability.py

@@ -0,0 +1,431 @@
+"""Unified observability configuration for etcd3 client.
+
+This module provides a centralized configuration for tracing, logging, and
+metrics, allowing users to enable and configure observability features
+through a single interface.
+
+Environment Variables (all prefixed with ETCD_OBS_):
+    - ETCD_OBS_AUTO_INIT: Auto-initialize on first client create (default: true)
+    - ETCD_OBS_LOG_LEVEL: Log level (DEBUG, INFO, WARNING, ERROR)
+    - ETCD_OBS_LOG_FORMAT: Log format (text, json, colored)
+    - ETCD_OBS_LOG_SAMPLE_RATE: Log sampling rate (0.0-1.0)
+    - ETCD_OBS_LOG_SAMPLE_STRATEGY: Sampling strategy (always, rate, dynamic, level_based)
+    - ETCD_OBS_TRACING_ENABLED: Enable OpenTelemetry tracing (true/false)
+    - ETCD_OBS_TRACING_SERVICE_NAME: Service name for tracing
+    - ETCD_OBS_TRACING_SAMPLE_RATE: Trace sampling rate (0.0-1.0)
+    - ETCD_OBS_METRICS_ENABLED: Enable metrics collection (true/false)
+    - ETCD_OBS_PROMETHEUS_ENABLED: Enable Prometheus export (true/false)
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+import logging
+import os
+
+from etcd3.log_sampling import LogSampler, SamplingStrategy, set_sampler
+from etcd3.log_formatters import configure_formatter
+
+ENV_PREFIX = "ETCD_OBS_"
+
+_observability_initialized: bool = False
+
+
+def _parse_bool(value: str | None, default: bool) -> bool:
+    """Parse boolean from environment variable."""
+    if value is None:
+        return default
+    return value.lower() in ("true", "1", "yes", "on")
+
+
+def _parse_float(value: str | None, default: float) -> float:
+    """Parse float from environment variable."""
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return default
+
+
+def _parse_strategy(value: str | None) -> SamplingStrategy:
+    """Parse sampling strategy from environment variable."""
+    if value is None:
+        return SamplingStrategy.ALWAYS
+    strategy_map = {
+        "always": SamplingStrategy.ALWAYS,
+        "rate": SamplingStrategy.RATE,
+        "dynamic": SamplingStrategy.DYNAMIC,
+        "level_based": SamplingStrategy.LEVEL_BASED,
+    }
+    return strategy_map.get(value.lower(), SamplingStrategy.ALWAYS)
+
+
+@dataclass
+class ObservabilityConfig:
+    """Unified observability configuration.
+
+    Provides a single point of configuration for all observability features
+    including distributed tracing, structured logging, and metrics.
+
+    Example:
+        >>> config = ObservabilityConfig(
+        ...     tracing_enabled=True,
+        ...     log_format="json",
+        ...     log_level="INFO",
+        ... )
+        >>> config.apply()
+
+    Attributes:
+        tracing_enabled: Enable OpenTelemetry tracing
+        tracing_service_name: Service name for tracing
+        tracing_sample_rate: Trace sampling rate (0.0-1.0)
+        log_level: Log level (DEBUG, INFO, WARNING, ERROR)
+        log_format: Log format (text, json, colored)
+        log_sample_rate: Log sampling rate (0.0-1.0)
+        log_sampling_strategy: Log sampling strategy
+        log_level_overrides: Per-operation log level overrides
+        metrics_enabled: Enable metrics collection
+        inject_trace_to_logs: Include trace context in logs
+    """
+
+    # ===== Tracing Configuration =====
+    tracing_enabled: bool = True
+    tracing_service_name: str = "etcd3-client"
+    tracing_sample_rate: float = 1.0
+
+    # ===== Logging Configuration =====
+    log_level: str = "INFO"
+    log_format: str = "text"  # text, json, colored
+    log_sample_rate: float = 1.0
+    log_sampling_strategy: SamplingStrategy = SamplingStrategy.ALWAYS
+    log_level_overrides: Dict[str, str] = field(default_factory=dict)
+
+    # ===== Metrics Configuration =====
+    metrics_enabled: bool = True
+    prometheus_enabled: bool = False
+
+    # ===== Integration Configuration =====
+    inject_trace_to_logs: bool = True
+
+    def __post_init__(self):
+        """Validate configuration and initialize components."""
+        self._validate()
+        self._init_sampler()
+
+    def _validate(self):
+        """Validate configuration values.
+
+        :raises ValueError: If configuration is invalid
+        """
+        valid_formats = ["text", "json", "colored"]
+        if self.log_format not in valid_formats:
+            raise ValueError(
+                f"log_format must be one of {valid_formats}, got '{self.log_format}'"
+            )
+
+        if not 0.0 <= self.tracing_sample_rate <= 1.0:
+            raise ValueError(
+                f"tracing_sample_rate must be between 0.0 and 1.0, "
+                f"got {self.tracing_sample_rate}"
+            )
+
+        if not 0.0 <= self.log_sample_rate <= 1.0:
+            raise ValueError(
+                f"log_sample_rate must be between 0.0 and 1.0, "
+                f"got {self.log_sample_rate}"
+            )
+
+        # Validate log level
+        valid_levels = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+        if self.log_level.upper() not in valid_levels:
+            raise ValueError(
+                f"log_level must be one of {valid_levels}, got '{self.log_level}'"
+            )
+
+    def _init_sampler(self):
+        """Initialize log sampler based on configuration."""
+        self._sampler = LogSampler(
+            strategy=self.log_sampling_strategy,
+            rate=self.log_sample_rate,
+        )
+
+    def apply(self):
+        """Apply configuration to all observability components.
+
+        This method configures:
+        - Logging level and format
+        - Tracing initialization
+        - Log sampling
+        - Prometheus metrics (if enabled)
+
+        Example:
+            >>> config = ObservabilityConfig(log_format="json")
+            >>> config.apply()
+            >>> # Now all etcd3 logs will be in JSON format
+        """
+        from etcd3.log import get_logger, set_log_level
+
+        # 1. Configure log level
+        set_log_level(self.log_level)
+
+        # 2. Configure log format
+        logger = get_logger()
+
+        # Clear existing handlers and add new one
+        logger.handlers.clear()
+        handler = logging.StreamHandler()
+        handler.setFormatter(configure_formatter(self.log_format))
+        logger.addHandler(handler)
+
+        # 3. Initialize tracing if enabled
+        if self.tracing_enabled:
+            from etcd3.trace import init_tracing
+
+            init_tracing(
+                service_name=self.tracing_service_name,
+                sample_rate=self.tracing_sample_rate,
+            )
+
+        # 4. Set global log sampler
+        set_sampler(self._sampler)
+
+        # 5. Initialize Prometheus metrics if enabled
+        if self.prometheus_enabled:
+            self._init_prometheus()
+
+        # Mark as initialized
+        global _observability_initialized
+        _observability_initialized = True
+
+    def _init_prometheus(self):
+        """Initialize Prometheus exporter."""
+        try:
+            from etcd3.exporters.prometheus import (
+                init_exporter,
+                is_prometheus_available,
+            )
+
+            if not is_prometheus_available():
+                import logging
+
+                logging.getLogger("etcd3").warning(
+                    "prometheus_client not installed. "
+                    "Install with: pip install prometheus-client"
+                )
+                return
+
+            init_exporter()
+        except Exception as e:
+            import logging
+
+            logging.getLogger("etcd3").warning(
+                f"Failed to initialize Prometheus exporter: {e}"
+            )
+
+    def get_prometheus_metrics(self) -> Optional[bytes]:
+        """Get Prometheus metrics in text format.
+
+        Returns:
+            Prometheus metrics text format or None if not available
+        """
+        if not self.prometheus_enabled:
+            return None
+
+        try:
+            from etcd3.exporters.prometheus import get_exporter
+
+            exporter = get_exporter()
+            if exporter:
+                return exporter.metrics()
+        except Exception:
+            pass
+        return None
+
+    def get_log_level_for_operation(self, operation: str) -> int:
+        """Get the effective log level for a specific operation.
+
+        Checks for operation-specific overrides before returning the
+        default log level.
+
+        :param operation: Operation name (e.g., "kv.get", "lease.keepalive")
+        :returns: Log level as integer (logging.DEBUG, etc.)
+
+        Example:
+            >>> config = ObservabilityConfig(
+            ...     log_level="INFO",
+            ...     log_level_overrides={"lease.keepalive": "WARNING"}
+            ... )
+            >>> config.get_log_level_for_operation("kv.get")
+            20  # INFO
+            >>> config.get_log_level_for_operation("lease.keepalive")
+            30  # WARNING
+        """
+        level_str = self.log_level_overrides.get(operation)
+        if level_str:
+            return getattr(logging, level_str.upper(), logging.INFO)
+        return getattr(logging, self.log_level.upper(), logging.INFO)
+
+    def should_log_operation(self, operation: str, level: int) -> bool:
+        """Check if an operation should be logged at the given level.
+
+        Combines operation-specific level configuration with global
+        sampling strategy.
+
+        :param operation: Operation name
+        :param level: Log level to check
+        :returns: True if should log
+        """
+        effective_level = self.get_log_level_for_operation(operation)
+        if level < effective_level:
+            return False
+
+        return self._sampler.should_log(level, operation)
+
+
+def get_default_config() -> ObservabilityConfig:
+    """Get default observability configuration.
+
+    Creates a configuration with sensible defaults suitable for
+    most production deployments.
+
+    :returns: Default ObservabilityConfig
+
+    Example:
+        >>> config = get_default_config()
+        >>> config.apply()
+    """
+    return ObservabilityConfig(
+        tracing_enabled=True,
+        tracing_service_name="etcd3-client",
+        log_level="INFO",
+        log_format="text",
+        log_sample_rate=1.0,
+        metrics_enabled=True,
+    )
+
+
+def get_development_config() -> ObservabilityConfig:
+    """Get development-friendly observability configuration.
+
+    Creates a configuration optimized for development with verbose
+    logging and full tracing.
+
+    :returns: Development ObservabilityConfig
+
+    Example:
+        >>> config = get_development_config()
+        >>> config.apply()
+    """
+    return ObservabilityConfig(
+        tracing_enabled=True,
+        tracing_service_name="etcd3-client-dev",
+        log_level="DEBUG",
+        log_format="colored",
+        log_sample_rate=1.0,
+        metrics_enabled=True,
+    )
+
+
+def get_production_config() -> ObservabilityConfig:
+    """Get production-optimized observability configuration.
+
+    Creates a configuration optimized for production with structured
+    logging, sampling, and moderate log levels.
+
+    :returns: Production ObservabilityConfig
+
+    Example:
+        >>> config = get_production_config()
+        >>> config.apply()
+    """
+    return ObservabilityConfig(
+        tracing_enabled=True,
+        tracing_service_name="etcd3-client",
+        tracing_sample_rate=0.1,  # Sample 10% of traces
+        log_level="INFO",
+        log_format="json",
+        log_sample_rate=0.5,  # Sample 50% of logs
+        log_sampling_strategy=SamplingStrategy.RATE,
+        log_level_overrides={
+            "lease.keepalive": "WARNING",  # Reduce keepalive noise
+        },
+        metrics_enabled=True,
+        prometheus_enabled=True,
+    )
+
+
+def configure_from_env() -> ObservabilityConfig:
+    """Create configuration from environment variables.
+
+    All environment variables are prefixed with ETCD_OBS_:
+    - ETCD_OBS_AUTO_INIT: Auto-initialize on first client create (default: true)
+    - ETCD_OBS_LOG_LEVEL: DEBUG, INFO, WARNING, ERROR
+    - ETCD_OBS_LOG_FORMAT: text, json, colored
+    - ETCD_OBS_LOG_SAMPLE_RATE: Float 0.0-1.0
+    - ETCD_OBS_LOG_SAMPLE_STRATEGY: always, rate, dynamic, level_based
+    - ETCD_OBS_TRACING_ENABLED: true or false
+    - ETCD_OBS_TRACING_SERVICE_NAME: Service name
+    - ETCD_OBS_TRACING_SAMPLE_RATE: Float 0.0-1.0
+    - ETCD_OBS_METRICS_ENABLED: true or false
+    - ETCD_OBS_PROMETHEUS_ENABLED: true or false
+
+    :returns: Configured ObservabilityConfig
+    """
+    return ObservabilityConfig(
+        log_level=os.environ.get(f"{ENV_PREFIX}LOG_LEVEL", "INFO"),
+        log_format=os.environ.get(f"{ENV_PREFIX}LOG_FORMAT", "text"),
+        log_sample_rate=_parse_float(
+            os.environ.get(f"{ENV_PREFIX}LOG_SAMPLE_RATE"), 1.0
+        ),
+        log_sampling_strategy=_parse_strategy(
+            os.environ.get(f"{ENV_PREFIX}LOG_SAMPLE_STRATEGY")
+        ),
+        tracing_enabled=_parse_bool(
+            os.environ.get(f"{ENV_PREFIX}TRACING_ENABLED"), True
+        ),
+        tracing_service_name=os.environ.get(
+            f"{ENV_PREFIX}TRACING_SERVICE_NAME", "etcd3-client"
+        ),
+        tracing_sample_rate=_parse_float(
+            os.environ.get(f"{ENV_PREFIX}TRACING_SAMPLE_RATE"), 1.0
+        ),
+        metrics_enabled=_parse_bool(
+            os.environ.get(f"{ENV_PREFIX}METRICS_ENABLED"), True
+        ),
+        prometheus_enabled=_parse_bool(
+            os.environ.get(f"{ENV_PREFIX}PROMETHEUS_ENABLED"), False
+        ),
+    )
+
+
+def auto_init() -> bool:
+    """Automatically initialize observability based on environment variables.
+
+    This function is called on first client creation to set up logging,
+    tracing, and metrics if not already configured.
+
+    Returns:
+        True if initialization was performed, False if already initialized
+    """
+    global _observability_initialized
+
+    if _observability_initialized:
+        return False
+
+    # Check if auto-init is enabled (default: true)
+    if not _parse_bool(os.environ.get(f"{ENV_PREFIX}AUTO_INIT"), True):
+        return False
+
+    config = configure_from_env()
+    config.apply()
+    _observability_initialized = True
+    return True
+
+
+def is_initialized() -> bool:
+    """Check if observability has been initialized.
+
+    Returns:
+        True if observability has been initialized
+    """
+    return _observability_initialized