provide-foundation 0.0.0.dev0__py3-none-any.whl

provide/foundation/logger/setup/emoji_resolver.py

@@ -0,0 +1,64 @@
+#
+# emoji_resolver.py
+#
+"""
+Emoji configuration resolution for Foundation Telemetry.
+Handles the merging and resolution of emoji set configurations from multiple sources.
+"""
+
+from provide.foundation.logger.config import LoggingConfig
+from provide.foundation.logger.emoji.sets import LEGACY_DAS_EMOJI_SETS
+from provide.foundation.logger.emoji.types import (
+    EmojiSet,
+    EmojiSetConfig,
+    FieldToEmojiMapping,
+)
+
+ResolvedEmojiConfig = tuple[list[FieldToEmojiMapping], dict[str, EmojiSet]]
+
+
+def resolve_active_emoji_config(
+    logging_config: LoggingConfig, builtin_emoji_registry: dict[str, EmojiSetConfig]
+) -> ResolvedEmojiConfig:
+    """
+    Resolve the active emoji configuration from multiple sources.
+
+    Args:
+        logging_config: The logging configuration
+        builtin_emoji_registry: Registry of built-in emoji sets
+
+    Returns:
+        Tuple of (field_definitions, emoji_sets_dict)
+    """
+    resolved_fields_dict: dict[str, FieldToEmojiMapping] = {}
+    resolved_emoji_sets_dict: dict[str, EmojiSet] = {
+        s.name: s for s in LEGACY_DAS_EMOJI_SETS
+    }
+
+    emoji_sets_to_process: list[EmojiSetConfig] = [
+        builtin_emoji_registry[name]
+        for name in logging_config.enabled_emoji_sets
+        if name in builtin_emoji_registry
+    ]
+    emoji_sets_to_process.extend(logging_config.custom_emoji_sets)
+    emoji_sets_to_process.sort(key=lambda emoji_set: emoji_set.priority)
+
+    ordered_log_keys: list[str] = []
+    seen_log_keys: set[str] = set()
+
+    for emoji_set_config in emoji_sets_to_process:
+        for emoji_set in emoji_set_config.emoji_sets:
+            resolved_emoji_sets_dict[emoji_set.name] = emoji_set
+        for field_def in emoji_set_config.field_definitions:
+            resolved_fields_dict[field_def.log_key] = field_def
+            if field_def.log_key not in seen_log_keys:
+                ordered_log_keys.append(field_def.log_key)
+                seen_log_keys.add(field_def.log_key)
+
+    for user_emoji_set in logging_config.user_defined_emoji_sets:
+        resolved_emoji_sets_dict[user_emoji_set.name] = user_emoji_set
+
+    final_ordered_field_definitions = [
+        resolved_fields_dict[log_key] for log_key in ordered_log_keys
+    ]
+    return final_ordered_field_definitions, resolved_emoji_sets_dict

provide/foundation/logger/setup/processors.py

@@ -0,0 +1,85 @@
+#
+# processors.py
+#
+"""
+Processor chain building for Foundation Telemetry.
+Handles the assembly of structlog processor chains including emoji processing.
+"""
+
+from typing import Any, TextIO, cast
+
+import structlog
+
+from provide.foundation.logger.config import TelemetryConfig
+from provide.foundation.logger.processors import (
+    _build_core_processors_list,
+    _build_formatter_processors_list,
+)
+from provide.foundation.logger.setup.emoji_resolver import ResolvedEmojiConfig
+
+
+def build_complete_processor_chain(
+    config: TelemetryConfig,
+    resolved_emoji_config: ResolvedEmojiConfig,
+    log_stream: TextIO,
+) -> list[Any]:
+    """
+    Build the complete processor chain for structlog.
+
+    Args:
+        config: Telemetry configuration
+        resolved_emoji_config: Resolved emoji configuration
+        log_stream: Output stream for logging
+
+    Returns:
+        List of processors for structlog
+    """
+    core_processors = _build_core_processors_list(config, resolved_emoji_config)
+    formatter_processors = _build_formatter_processors_list(config.logging, log_stream)
+    return cast(list[Any], core_processors + formatter_processors)
+
+
+def apply_structlog_configuration(processors: list[Any], log_stream: TextIO) -> None:
+    """
+    Apply the processor configuration to structlog.
+
+    Args:
+        processors: List of processors to configure
+        log_stream: Output stream for logging
+    """
+    structlog.configure(
+        processors=processors,
+        logger_factory=structlog.PrintLoggerFactory(file=log_stream),
+        wrapper_class=cast(type[structlog.types.BindableLogger], structlog.BoundLogger),
+        cache_logger_on_first_use=True,
+    )
+
+
+def configure_structlog_output(
+    config: TelemetryConfig,
+    resolved_emoji_config: ResolvedEmojiConfig,
+    log_stream: TextIO,
+) -> None:
+    """
+    Configure structlog with the complete output chain.
+
+    Args:
+        config: Telemetry configuration
+        resolved_emoji_config: Resolved emoji configuration
+        log_stream: Output stream for logging
+    """
+    processors = build_complete_processor_chain(
+        config, resolved_emoji_config, log_stream
+    )
+    apply_structlog_configuration(processors, log_stream)
+
+
+def handle_globally_disabled_setup() -> None:
+    """
+    Configure structlog for globally disabled telemetry (no-op mode).
+    """
+    structlog.configure(
+        processors=[],
+        logger_factory=structlog.ReturnLoggerFactory(),
+        cache_logger_on_first_use=True,
+    )

provide/foundation/logger/setup/testing.py

@@ -0,0 +1,39 @@
+#
+# testing.py
+#
+"""
+Testing utilities for Foundation Telemetry setup.
+Provides functions to reset state and configure test environments.
+"""
+
+import structlog
+
+from provide.foundation.logger.core import (
+    _LAZY_SETUP_STATE,
+    logger as foundation_logger,
+)
+from provide.foundation.streams.file import reset_streams
+
+
+def reset_foundation_state() -> None:
+    """
+    Internal function to reset structlog and Foundation Telemetry's state.
+    """
+    # Reset structlog configuration
+    structlog.reset_defaults()
+
+    # Reset stream state
+    reset_streams()
+
+    # Reset foundation logger state
+    foundation_logger._is_configured_by_setup = False
+    foundation_logger._active_config = None
+    foundation_logger._active_resolved_emoji_config = None
+    _LAZY_SETUP_STATE.update({"done": False, "error": None, "in_progress": False})
+
+
+def reset_foundation_setup_for_testing() -> None:
+    """
+    Public test utility to reset Foundation Telemetry's internal state.
+    """
+    reset_foundation_state()

provide/foundation/logger/trace.py

@@ -0,0 +1,38 @@
+#
+# trace.py
+#
+"""
+TRACE log level setup and patching.
+
+This module handles the custom TRACE log level implementation,
+including patching the standard library logging module.
+"""
+
+import logging as stdlib_logging
+from typing import Any, cast
+
+# --- TRACE Level Constants ---
+TRACE_LEVEL_NUM: int = 5  # Typically, DEBUG is 10, so TRACE is lower
+"""Numeric value for the custom TRACE log level."""
+
+TRACE_LEVEL_NAME: str = "TRACE"
+"""String name for the custom TRACE log level."""
+
+# Add TRACE to standard library logging if it doesn't exist
+if not hasattr(stdlib_logging, TRACE_LEVEL_NAME):  # pragma: no cover
+    stdlib_logging.addLevelName(TRACE_LEVEL_NUM, TRACE_LEVEL_NAME)
+
+    def trace(
+        self: stdlib_logging.Logger, message: str, *args: object, **kwargs: object
+    ) -> None:  # pragma: no cover
+        if self.isEnabledFor(TRACE_LEVEL_NUM):
+            self._log(TRACE_LEVEL_NUM, message, args, **kwargs)  # type: ignore[arg-type]
+
+    if not hasattr(stdlib_logging.Logger, "trace"):  # pragma: no cover
+        stdlib_logging.Logger.trace = trace  # type: ignore[attr-defined]
+    if stdlib_logging.root and not hasattr(
+        stdlib_logging.root, "trace"
+    ):  # pragma: no cover
+        (cast(Any, stdlib_logging.root)).trace = trace.__get__(
+            stdlib_logging.root, stdlib_logging.Logger
+        )

provide/foundation/metrics/__init__.py

@@ -0,0 +1,119 @@
+"""
+Foundation Metrics Module.
+
+Provides metrics collection with optional OpenTelemetry integration.
+Falls back to simple metrics when OpenTelemetry is not available.
+"""
+
+# OpenTelemetry feature detection
+try:
+    from opentelemetry import metrics as otel_metrics
+    from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+        OTLPMetricExporter as OTLPGrpcMetricExporter,
+    )
+    from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
+        OTLPMetricExporter as OTLPHttpMetricExporter,
+    )
+    from opentelemetry.sdk.metrics import MeterProvider
+    from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+
+    _HAS_OTEL_METRICS = True
+except ImportError:
+    otel_metrics = None
+    MeterProvider = None
+    PeriodicExportingMetricReader = None
+    OTLPGrpcMetricExporter = None
+    OTLPHttpMetricExporter = None
+    _HAS_OTEL_METRICS = False
+
+from provide.foundation.metrics.simple import (
+    SimpleCounter,
+    SimpleGauge,
+    SimpleHistogram,
+)
+
+# Export the main API
+__all__ = [
+    "_HAS_OTEL_METRICS",  # For internal use
+    "counter",
+    "gauge",
+    "histogram",
+]
+
+# Global meter instance (will be set during setup)
+_meter = None
+
+
+def counter(name: str, description: str = "", unit: str = "") -> "SimpleCounter":
+    """Create a counter metric.
+
+    Args:
+        name: Name of the counter
+        description: Description of what this counter measures
+        unit: Unit of measurement
+
+    Returns:
+        Counter instance
+    """
+    if _HAS_OTEL_METRICS and _meter:
+        try:
+            otel_counter = _meter.create_counter(
+                name=name, description=description, unit=unit
+            )
+            return SimpleCounter(name, otel_counter=otel_counter)
+        except Exception:
+            pass
+
+    return SimpleCounter(name)
+
+
+def gauge(name: str, description: str = "", unit: str = "") -> "SimpleGauge":
+    """Create a gauge metric.
+
+    Args:
+        name: Name of the gauge
+        description: Description of what this gauge measures
+        unit: Unit of measurement
+
+    Returns:
+        Gauge instance
+    """
+    if _HAS_OTEL_METRICS and _meter:
+        try:
+            otel_gauge = _meter.create_up_down_counter(
+                name=name, description=description, unit=unit
+            )
+            return SimpleGauge(name, otel_gauge=otel_gauge)
+        except Exception:
+            pass
+
+    return SimpleGauge(name)
+
+
+def histogram(name: str, description: str = "", unit: str = "") -> "SimpleHistogram":
+    """Create a histogram metric.
+
+    Args:
+        name: Name of the histogram
+        description: Description of what this histogram measures
+        unit: Unit of measurement
+
+    Returns:
+        Histogram instance
+    """
+    if _HAS_OTEL_METRICS and _meter:
+        try:
+            otel_histogram = _meter.create_histogram(
+                name=name, description=description, unit=unit
+            )
+            return SimpleHistogram(name, otel_histogram=otel_histogram)
+        except Exception:
+            pass
+
+    return SimpleHistogram(name)
+
+
+def _set_meter(meter) -> None:
+    """Set the global meter instance (internal use only)."""
+    global _meter
+    _meter = meter

provide/foundation/metrics/otel.py

@@ -0,0 +1,122 @@
+"""OpenTelemetry metrics integration."""
+
+from provide.foundation.logger import get_logger
+from provide.foundation.logger.config.telemetry import TelemetryConfig
+
+log = get_logger(__name__)
+
+# Feature detection
+try:
+    from opentelemetry import metrics as otel_metrics
+    from opentelemetry.exporter.otlp.proto.grpc.metric_exporter import (
+        OTLPMetricExporter as OTLPGrpcMetricExporter,
+    )
+    from opentelemetry.exporter.otlp.proto.http.metric_exporter import (
+        OTLPMetricExporter as OTLPHttpMetricExporter,
+    )
+    from opentelemetry.sdk.metrics import MeterProvider
+    from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
+    from opentelemetry.sdk.resources import Resource
+
+    _HAS_OTEL_METRICS = True
+except ImportError:
+    _HAS_OTEL_METRICS = False
+    # Stub everything
+    otel_metrics = None
+    MeterProvider = None
+    PeriodicExportingMetricReader = None
+    Resource = None
+    OTLPGrpcMetricExporter = None
+    OTLPHttpMetricExporter = None
+
+
+def _require_otel_metrics() -> None:
+    """Ensure OpenTelemetry metrics are available."""
+    if not _HAS_OTEL_METRICS:
+        raise ImportError(
+            "OpenTelemetry metrics require optional dependencies. "
+            "Install with: pip install 'provide-foundation[opentelemetry]'"
+        )
+
+
+def setup_opentelemetry_metrics(config: TelemetryConfig) -> None:
+    """Setup OpenTelemetry metrics with configuration.
+
+    Args:
+        config: Telemetry configuration
+    """
+    # Check if metrics are disabled first, before checking dependencies
+    if not config.metrics_enabled or config.globally_disabled:
+        log.debug("📊 OpenTelemetry metrics disabled")
+        return
+
+    # Check if OpenTelemetry metrics are available
+    if not _HAS_OTEL_METRICS:
+        log.debug("📊 OpenTelemetry metrics not available (dependencies not installed)")
+        return
+
+    log.debug("📊🚀 Setting up OpenTelemetry metrics")
+
+    # Create resource with service information
+    resource_attrs = {}
+    if config.service_name:
+        resource_attrs["service.name"] = config.service_name
+    if config.service_version:
+        resource_attrs["service.version"] = config.service_version
+
+    resource = Resource.create(resource_attrs)
+
+    # Setup metric readers with OTLP exporters if configured
+    readers = []
+
+    if config.otlp_endpoint:
+        endpoint = config.otlp_endpoint
+        headers = config.get_otlp_headers_dict()
+
+        log.debug(f"📊📤 Configuring OTLP metrics exporter: {endpoint}")
+
+        # Choose exporter based on protocol
+        if config.otlp_protocol == "grpc":
+            exporter = OTLPGrpcMetricExporter(
+                endpoint=endpoint,
+                headers=headers,
+            )
+        else:  # http/protobuf
+            exporter = OTLPHttpMetricExporter(
+                endpoint=endpoint,
+                headers=headers,
+            )
+
+        # Create periodic reader (exports every 60 seconds by default)
+        reader = PeriodicExportingMetricReader(exporter, export_interval_millis=60000)
+        readers.append(reader)
+
+        log.debug(f"✅ OTLP metrics exporter configured: {config.otlp_protocol}")
+
+    # Create meter provider
+    meter_provider = MeterProvider(resource=resource, metric_readers=readers)
+
+    # Set the global meter provider
+    otel_metrics.set_meter_provider(meter_provider)
+
+    # Set the global meter for our metrics module
+    from provide.foundation.metrics import _set_meter
+
+    meter = otel_metrics.get_meter(__name__)
+    _set_meter(meter)
+
+    log.info("📊✅ OpenTelemetry metrics setup complete")
+
+
+def shutdown_opentelemetry_metrics() -> None:
+    """Shutdown OpenTelemetry metrics."""
+    if not _HAS_OTEL_METRICS:
+        return
+
+    try:
+        meter_provider = otel_metrics.get_meter_provider()
+        if hasattr(meter_provider, "shutdown"):
+            meter_provider.shutdown()
+            log.debug("📊🛑 OpenTelemetry meter provider shutdown")
+    except Exception as e:
+        log.warning(f"⚠️ Error shutting down OpenTelemetry metrics: {e}")

provide/foundation/metrics/simple.py

@@ -0,0 +1,165 @@
+"""Simple metrics implementations that work with or without OpenTelemetry."""
+
+from collections import defaultdict
+from typing import Any
+
+from provide.foundation.logger import get_logger
+
+log = get_logger(__name__)
+
+
+class SimpleCounter:
+    """Counter metric that increments monotonically."""
+
+    def __init__(self, name: str, otel_counter: Any | None = None):
+        self.name = name
+        self._otel_counter = otel_counter
+        self._value = 0
+        self._labels_values: dict[str, float] = defaultdict(float)
+
+    def inc(self, value: float = 1, **labels) -> None:
+        """Increment the counter.
+
+        Args:
+            value: Amount to increment by (default: 1)
+            **labels: Label key-value pairs
+        """
+        self._value += value
+
+        # Track per-label values for simple mode
+        if labels:
+            labels_key = ",".join(f"{k}={v}" for k, v in sorted(labels.items()))
+            self._labels_values[labels_key] += value
+
+        # Use OpenTelemetry counter if available
+        if self._otel_counter:
+            try:
+                self._otel_counter.add(value, attributes=labels)
+            except Exception as e:
+                log.debug(f"📊⚠️ Failed to record OpenTelemetry counter: {e}")
+
+    @property
+    def value(self) -> float:
+        """Get the current counter value."""
+        return self._value
+
+
+class SimpleGauge:
+    """Gauge metric that can go up or down."""
+
+    def __init__(self, name: str, otel_gauge: Any | None = None):
+        self.name = name
+        self._otel_gauge = otel_gauge
+        self._value = 0
+        self._labels_values: dict[str, float] = defaultdict(float)
+
+    def set(self, value: float, **labels) -> None:
+        """Set the gauge value.
+
+        Args:
+            value: Value to set
+            **labels: Label key-value pairs
+        """
+        self._value = value
+
+        # Track per-label values for simple mode
+        if labels:
+            labels_key = ",".join(f"{k}={v}" for k, v in sorted(labels.items()))
+            self._labels_values[labels_key] = value
+
+        # Use OpenTelemetry gauge if available
+        if self._otel_gauge:
+            try:
+                self._otel_gauge.add(
+                    value
+                    - self._labels_values.get(
+                        ",".join(f"{k}={v}" for k, v in sorted(labels.items()))
+                        if labels
+                        else "",
+                        0,
+                    ),
+                    attributes=labels,
+                )
+            except Exception as e:
+                log.debug(f"📊⚠️ Failed to record OpenTelemetry gauge: {e}")
+
+    def inc(self, value: float = 1, **labels) -> None:
+        """Increment the gauge value.
+
+        Args:
+            value: Amount to increment by
+            **labels: Label key-value pairs
+        """
+        self._value += value
+
+        if labels:
+            labels_key = ",".join(f"{k}={v}" for k, v in sorted(labels.items()))
+            self._labels_values[labels_key] += value
+
+        if self._otel_gauge:
+            try:
+                self._otel_gauge.add(value, attributes=labels)
+            except Exception as e:
+                log.debug(f"📊⚠️ Failed to increment OpenTelemetry gauge: {e}")
+
+    def dec(self, value: float = 1, **labels) -> None:
+        """Decrement the gauge value.
+
+        Args:
+            value: Amount to decrement by
+            **labels: Label key-value pairs
+        """
+        self.inc(-value, **labels)
+
+    @property
+    def value(self) -> float:
+        """Get the current gauge value."""
+        return self._value
+
+
+class SimpleHistogram:
+    """Histogram metric for recording distributions of values."""
+
+    def __init__(self, name: str, otel_histogram: Any | None = None):
+        self.name = name
+        self._otel_histogram = otel_histogram
+        self._observations: list[float] = []
+        self._labels_observations: dict[str, list[float]] = defaultdict(list)
+
+    def observe(self, value: float, **labels) -> None:
+        """Record an observation.
+
+        Args:
+            value: Value to observe
+            **labels: Label key-value pairs
+        """
+        self._observations.append(value)
+
+        # Track per-label observations for simple mode
+        if labels:
+            labels_key = ",".join(f"{k}={v}" for k, v in sorted(labels.items()))
+            self._labels_observations[labels_key].append(value)
+
+        # Use OpenTelemetry histogram if available
+        if self._otel_histogram:
+            try:
+                self._otel_histogram.record(value, attributes=labels)
+            except Exception as e:
+                log.debug(f"📊⚠️ Failed to record OpenTelemetry histogram: {e}")
+
+    @property
+    def count(self) -> int:
+        """Get the number of observations."""
+        return len(self._observations)
+
+    @property
+    def sum(self) -> float:
+        """Get the sum of all observations."""
+        return sum(self._observations)
+
+    @property
+    def avg(self) -> float:
+        """Get the average of all observations."""
+        if not self._observations:
+            return 0.0
+        return self.sum / self.count

provide/foundation/observability/__init__.py

@@ -0,0 +1,53 @@
+"""
+Observability module for Foundation.
+
+Provides integration with observability platforms like OpenObserve.
+Only available when OpenTelemetry dependencies are installed.
+"""
+
+# OpenTelemetry feature detection
+try:
+    from opentelemetry import trace as otel_trace
+
+    _HAS_OTEL = True
+except ImportError:
+    otel_trace = None
+    _HAS_OTEL = False
+
+# Only import OpenObserve if OpenTelemetry is available
+if _HAS_OTEL:
+    try:
+        from provide.foundation.observability.openobserve import (
+            OpenObserveClient,
+            search_logs,
+            stream_logs,
+        )
+
+        # Commands will auto-register if click is available
+        try:
+            from provide.foundation.observability.openobserve.commands import (
+                openobserve_group,
+            )
+        except ImportError:
+            # Click not available, skip command registration
+            pass
+
+        __all__ = [
+            "OpenObserveClient",
+            "search_logs",
+            "stream_logs",
+        ]
+    except ImportError:
+        # OpenObserve module not fully available
+        __all__ = []
+else:
+    __all__ = []
+
+
+def is_openobserve_available() -> bool:
+    """Check if OpenObserve integration is available.
+
+    Returns:
+        True if OpenTelemetry and OpenObserve are available
+    """
+    return _HAS_OTEL and "OpenObserveClient" in globals()