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

provide/foundation/logger/config/logging.py

@@ -0,0 +1,394 @@
+#
+# logging.py
+#
+"""
+LoggingConfig class for Foundation logger configuration.
+"""
+
+import json
+import os
+from pathlib import Path
+
+from attrs import define
+
+from provide.foundation.config import BaseConfig, field
+from provide.foundation.config.types import ConfigSource
+from provide.foundation.logger.config.base import get_config_logger
+from provide.foundation.logger.emoji.types import EmojiSet, EmojiSetConfig
+from provide.foundation.types import (
+    _VALID_FORMATTER_TUPLE,
+    _VALID_LOG_LEVEL_TUPLE,
+    ConsoleFormatterStr,
+    LogLevelStr,
+)
+
+
+@define(slots=True, repr=False)
+class LoggingConfig(BaseConfig):
+    """Configuration specific to logging behavior within Foundation Telemetry."""
+
+    default_level: LogLevelStr = field(
+        default="DEBUG",
+        env_var="PROVIDE_LOG_LEVEL",
+        description="Default logging level",
+    )
+    module_levels: dict[str, LogLevelStr] = field(
+        factory=lambda: {},
+        env_var="PROVIDE_LOG_MODULE_LEVELS",
+        description="Per-module log levels (format: module1:LEVEL,module2:LEVEL)",
+    )
+    console_formatter: ConsoleFormatterStr = field(
+        default="key_value",
+        env_var="PROVIDE_LOG_CONSOLE_FORMATTER",
+        description="Console output formatter (key_value or json)",
+    )
+    logger_name_emoji_prefix_enabled: bool = field(
+        default=True,
+        env_var="PROVIDE_LOG_LOGGER_NAME_EMOJI_ENABLED",
+        description="Enable emoji prefixes based on logger names",
+    )
+    das_emoji_prefix_enabled: bool = field(
+        default=True,
+        env_var="PROVIDE_LOG_DAS_EMOJI_ENABLED",
+        description="Enable Domain-Action-Status emoji prefixes",
+    )
+    omit_timestamp: bool = field(
+        default=False,
+        env_var="PROVIDE_LOG_OMIT_TIMESTAMP",
+        description="Omit timestamps from console output",
+    )
+    enabled_emoji_sets: list[str] = field(
+        factory=lambda: [],
+        env_var="PROVIDE_LOG_ENABLED_EMOJI_SETS",
+        description="Comma-separated list of emoji sets to enable",
+    )
+    custom_emoji_sets: list[EmojiSetConfig] = field(
+        factory=lambda: [],
+        env_var="PROVIDE_LOG_CUSTOM_EMOJI_SETS",
+        description="JSON array of custom emoji set configurations",
+    )
+    user_defined_emoji_sets: list[EmojiSet] = field(
+        factory=lambda: [],
+        env_var="PROVIDE_LOG_USER_DEFINED_EMOJI_SETS",
+        description="JSON array of user-defined emoji sets",
+    )
+    log_file: Path | None = field(
+        default=None, env_var="PROVIDE_LOG_FILE", description="Path to log file"
+    )
+    foundation_setup_log_level: LogLevelStr = field(
+        default="INFO",
+        env_var="FOUNDATION_LOG_LEVEL",
+        description="Log level for Foundation internal setup messages",
+    )
+    foundation_log_output: str = field(
+        default="stderr",
+        env_var="FOUNDATION_LOG_OUTPUT",
+        description="Output destination for Foundation internal messages (stderr, stdout, main)",
+    )
+    show_emoji_matrix: bool = field(
+        default=False,
+        env_var="PROVIDE_SHOW_EMOJI_MATRIX",
+        description="Whether to display emoji matrix on startup",
+    )
+    rate_limit_enabled: bool = field(
+        default=False,
+        env_var="PROVIDE_LOG_RATE_LIMIT_ENABLED",
+        description="Enable rate limiting for log output",
+    )
+    rate_limit_global: float | None = field(
+        default=None,
+        env_var="PROVIDE_LOG_RATE_LIMIT_GLOBAL",
+        description="Global rate limit (logs per second)",
+    )
+    rate_limit_global_capacity: float | None = field(
+        default=None,
+        env_var="PROVIDE_LOG_RATE_LIMIT_GLOBAL_CAPACITY",
+        description="Global rate limit burst capacity",
+    )
+    rate_limit_per_logger: dict[str, tuple[float, float]] = field(
+        factory=lambda: {},
+        env_var="PROVIDE_LOG_RATE_LIMIT_PER_LOGGER",
+        description="Per-logger rate limits (format: logger1:rate:capacity,logger2:rate:capacity)",
+    )
+    rate_limit_emit_warnings: bool = field(
+        default=True,
+        env_var="PROVIDE_LOG_RATE_LIMIT_EMIT_WARNINGS",
+        description="Emit warnings when logs are rate limited",
+    )
+    rate_limit_summary_interval: float = field(
+        default=5.0,
+        env_var="PROVIDE_LOG_RATE_LIMIT_SUMMARY_INTERVAL",
+        description="Seconds between rate limit summary reports",
+    )
+    rate_limit_max_queue_size: int = field(
+        default=1000,
+        env_var="PROVIDE_LOG_RATE_LIMIT_MAX_QUEUE_SIZE",
+        description="Maximum number of logs to queue when rate limited",
+    )
+    rate_limit_max_memory_mb: float | None = field(
+        default=None,
+        env_var="PROVIDE_LOG_RATE_LIMIT_MAX_MEMORY_MB",
+        description="Maximum memory (MB) for queued logs",
+    )
+    rate_limit_overflow_policy: str = field(
+        default="drop_oldest",
+        env_var="PROVIDE_LOG_RATE_LIMIT_OVERFLOW_POLICY",
+        description="Policy when queue is full: drop_oldest, drop_newest, or block",
+    )
+
+    @classmethod
+    def from_env(cls, strict: bool = True) -> "LoggingConfig":
+        """Load LoggingConfig from environment variables."""
+        config_dict = {}
+
+        # Parse standard fields
+        if level := os.getenv("PROVIDE_LOG_LEVEL"):
+            level = level.upper()
+            if level in _VALID_LOG_LEVEL_TUPLE:
+                config_dict["default_level"] = level
+            elif strict:
+                get_config_logger().warning(
+                    "[Foundation Config Warning] Invalid configuration value, using default",
+                    config_key="PROVIDE_LOG_LEVEL",
+                    invalid_value=level,
+                    valid_options=list(_VALID_LOG_LEVEL_TUPLE),
+                    default_value="DEBUG",
+                )
+
+        if formatter := os.getenv("PROVIDE_LOG_CONSOLE_FORMATTER"):
+            formatter = formatter.lower()
+            if formatter in _VALID_FORMATTER_TUPLE:
+                config_dict["console_formatter"] = formatter
+            elif strict:
+                get_config_logger().warning(
+                    "[Foundation Config Warning] Invalid configuration value, using default",
+                    config_key="PROVIDE_LOG_CONSOLE_FORMATTER",
+                    invalid_value=formatter,
+                    valid_options=list(_VALID_FORMATTER_TUPLE),
+                    default_value="key_value",
+                )
+
+        if omit_ts := os.getenv("PROVIDE_LOG_OMIT_TIMESTAMP"):
+            config_dict["omit_timestamp"] = omit_ts.lower() == "true"
+
+        if logger_emoji := os.getenv("PROVIDE_LOG_LOGGER_NAME_EMOJI_ENABLED"):
+            config_dict["logger_name_emoji_prefix_enabled"] = (
+                logger_emoji.lower() == "true"
+            )
+
+        if das_emoji := os.getenv("PROVIDE_LOG_DAS_EMOJI_ENABLED"):
+            config_dict["das_emoji_prefix_enabled"] = das_emoji.lower() == "true"
+
+        if log_file := os.getenv("PROVIDE_LOG_FILE"):
+            config_dict["log_file"] = Path(log_file)
+
+        if foundation_level := os.getenv("FOUNDATION_LOG_LEVEL"):
+            foundation_level = foundation_level.upper()
+            if foundation_level in _VALID_LOG_LEVEL_TUPLE:
+                config_dict["foundation_setup_log_level"] = foundation_level
+            elif strict:
+                get_config_logger().warning(
+                    "[Foundation Config Warning] Invalid configuration value, using default",
+                    config_key="FOUNDATION_LOG_LEVEL",
+                    invalid_value=foundation_level,
+                    valid_options=list(_VALID_LOG_LEVEL_TUPLE),
+                    default_value="INFO",
+                )
+
+        if foundation_output := os.getenv("FOUNDATION_LOG_OUTPUT"):
+            foundation_output = foundation_output.lower()
+            valid_outputs = ("stderr", "stdout", "main")
+            if foundation_output in valid_outputs:
+                config_dict["foundation_log_output"] = foundation_output
+            elif strict:
+                get_config_logger().warning(
+                    "[Foundation Config Warning] Invalid configuration value, using default",
+                    config_key="FOUNDATION_LOG_OUTPUT",
+                    invalid_value=foundation_output,
+                    valid_options=list(valid_outputs),
+                    default_value="stderr",
+                )
+
+        if show_matrix := os.getenv("PROVIDE_SHOW_EMOJI_MATRIX"):
+            config_dict["show_emoji_matrix"] = show_matrix.strip().lower() in (
+                "true",
+                "1",
+                "yes",
+            )
+
+        # Parse rate limiting configuration
+        if rate_limit_enabled := os.getenv("PROVIDE_LOG_RATE_LIMIT_ENABLED"):
+            config_dict["rate_limit_enabled"] = rate_limit_enabled.lower() == "true"
+
+        if rate_limit_global := os.getenv("PROVIDE_LOG_RATE_LIMIT_GLOBAL"):
+            try:
+                config_dict["rate_limit_global"] = float(rate_limit_global)
+            except ValueError:
+                if strict:
+                    get_config_logger().warning(
+                        "[Foundation Config Warning] Invalid rate limit value",
+                        config_key="PROVIDE_LOG_RATE_LIMIT_GLOBAL",
+                        invalid_value=rate_limit_global,
+                    )
+
+        if rate_limit_capacity := os.getenv("PROVIDE_LOG_RATE_LIMIT_GLOBAL_CAPACITY"):
+            try:
+                config_dict["rate_limit_global_capacity"] = float(rate_limit_capacity)
+            except ValueError:
+                if strict:
+                    get_config_logger().warning(
+                        "[Foundation Config Warning] Invalid rate limit capacity",
+                        config_key="PROVIDE_LOG_RATE_LIMIT_GLOBAL_CAPACITY",
+                        invalid_value=rate_limit_capacity,
+                    )
+
+        if per_logger_limits := os.getenv("PROVIDE_LOG_RATE_LIMIT_PER_LOGGER"):
+            limits_dict = {}
+            for item in per_logger_limits.split(","):
+                parts = item.split(":")
+                if len(parts) == 3:
+                    logger_name, rate, capacity = parts
+                    try:
+                        limits_dict[logger_name.strip()] = (
+                            float(rate.strip()),
+                            float(capacity.strip()),
+                        )
+                    except ValueError:
+                        if strict:
+                            get_config_logger().warning(
+                                "[Foundation Config Warning] Invalid per-logger rate limit",
+                                config_key="PROVIDE_LOG_RATE_LIMIT_PER_LOGGER",
+                                invalid_item=item,
+                            )
+            if limits_dict:
+                config_dict["rate_limit_per_logger"] = limits_dict
+
+        if emit_warnings := os.getenv("PROVIDE_LOG_RATE_LIMIT_EMIT_WARNINGS"):
+            config_dict["rate_limit_emit_warnings"] = emit_warnings.lower() == "true"
+
+        if summary_interval := os.getenv("PROVIDE_LOG_RATE_LIMIT_SUMMARY_INTERVAL"):
+            try:
+                config_dict["rate_limit_summary_interval"] = float(summary_interval)
+            except ValueError:
+                if strict:
+                    get_config_logger().warning(
+                        "[Foundation Config Warning] Invalid summary interval",
+                        config_key="PROVIDE_LOG_RATE_LIMIT_SUMMARY_INTERVAL",
+                        invalid_value=summary_interval,
+                    )
+
+        if max_queue := os.getenv("PROVIDE_LOG_RATE_LIMIT_MAX_QUEUE_SIZE"):
+            try:
+                config_dict["rate_limit_max_queue_size"] = int(max_queue)
+            except ValueError:
+                if strict:
+                    get_config_logger().warning(
+                        "[Foundation Config Warning] Invalid max queue size",
+                        config_key="PROVIDE_LOG_RATE_LIMIT_MAX_QUEUE_SIZE",
+                        invalid_value=max_queue,
+                    )
+
+        if max_memory := os.getenv("PROVIDE_LOG_RATE_LIMIT_MAX_MEMORY_MB"):
+            try:
+                config_dict["rate_limit_max_memory_mb"] = float(max_memory)
+            except ValueError:
+                if strict:
+                    get_config_logger().warning(
+                        "[Foundation Config Warning] Invalid max memory",
+                        config_key="PROVIDE_LOG_RATE_LIMIT_MAX_MEMORY_MB",
+                        invalid_value=max_memory,
+                    )
+
+        if overflow_policy := os.getenv("PROVIDE_LOG_RATE_LIMIT_OVERFLOW_POLICY"):
+            valid_policies = ("drop_oldest", "drop_newest", "block")
+            if overflow_policy in valid_policies:
+                config_dict["rate_limit_overflow_policy"] = overflow_policy
+            elif strict:
+                get_config_logger().warning(
+                    "[Foundation Config Warning] Invalid overflow policy",
+                    config_key="PROVIDE_LOG_RATE_LIMIT_OVERFLOW_POLICY",
+                    invalid_value=overflow_policy,
+                    valid_options=list(valid_policies),
+                )
+
+        # Parse complex fields
+        if module_levels := os.getenv("PROVIDE_LOG_MODULE_LEVELS"):
+            levels_dict = {}
+            for item in module_levels.split(","):
+                if ":" in item:
+                    module, level = item.split(":", 1)
+                    module = module.strip()
+                    level = level.strip().upper()
+                    if module and level in _VALID_LOG_LEVEL_TUPLE:
+                        levels_dict[module] = level
+                    elif strict and module and level not in _VALID_LOG_LEVEL_TUPLE:
+                        get_config_logger().warning(
+                            "[Foundation Config Warning] Invalid module log level, skipping",
+                            config_key="PROVIDE_LOG_MODULE_LEVELS",
+                            module_name=module,
+                            invalid_level=level,
+                            valid_options=list(_VALID_LOG_LEVEL_TUPLE),
+                        )
+            if levels_dict:
+                config_dict["module_levels"] = levels_dict
+
+        if emoji_sets := os.getenv("PROVIDE_LOG_ENABLED_EMOJI_SETS"):
+            config_dict["enabled_emoji_sets"] = [
+                s.strip() for s in emoji_sets.split(",") if s.strip()
+            ]
+
+        if custom_sets := os.getenv("PROVIDE_LOG_CUSTOM_EMOJI_SETS"):
+            try:
+                parsed = json.loads(custom_sets)
+                if isinstance(parsed, list):
+                    config_dict["custom_emoji_sets"] = [
+                        EmojiSetConfig(**item) if isinstance(item, dict) else item
+                        for item in parsed
+                    ]
+            except json.JSONDecodeError as e:
+                if strict:
+                    get_config_logger().warning(
+                        "[Foundation Config Warning] Invalid JSON in configuration",
+                        config_key="PROVIDE_LOG_CUSTOM_EMOJI_SETS",
+                        error=str(e),
+                        config_value=custom_sets[:100] + "..."
+                        if len(custom_sets) > 100
+                        else custom_sets,
+                    )
+            except (TypeError, ValueError) as e:
+                if strict:
+                    get_config_logger().warning(
+                        "[Foundation Config Warning] Error parsing custom emoji set configuration",
+                        config_key="PROVIDE_LOG_CUSTOM_EMOJI_SETS",
+                        error=str(e),
+                        error_type=type(e).__name__,
+                    )
+
+        if user_sets := os.getenv("PROVIDE_LOG_USER_DEFINED_EMOJI_SETS"):
+            try:
+                parsed = json.loads(user_sets)
+                if isinstance(parsed, list):
+                    config_dict["user_defined_emoji_sets"] = [
+                        EmojiSet(**item) if isinstance(item, dict) else item
+                        for item in parsed
+                    ]
+            except json.JSONDecodeError as e:
+                if strict:
+                    get_config_logger().warning(
+                        "[Foundation Config Warning] Invalid JSON in configuration",
+                        config_key="PROVIDE_LOG_USER_DEFINED_EMOJI_SETS",
+                        error=str(e),
+                        config_value=user_sets[:100] + "..."
+                        if len(user_sets) > 100
+                        else user_sets,
+                    )
+            except (TypeError, ValueError) as e:
+                if strict:
+                    get_config_logger().warning(
+                        "[Foundation Config Warning] Error parsing user emoji set configuration",
+                        config_key="PROVIDE_LOG_USER_DEFINED_EMOJI_SETS",
+                        error=str(e),
+                        error_type=type(e).__name__,
+                    )
+
+        return cls.from_dict(config_dict, source=ConfigSource.ENV)

provide/foundation/logger/config/telemetry.py

@@ -0,0 +1,188 @@
+#
+# telemetry.py
+#
+"""
+TelemetryConfig class for Foundation telemetry configuration.
+"""
+
+import os
+
+from attrs import define
+
+from provide.foundation.config import BaseConfig, field
+from provide.foundation.logger.config.logging import LoggingConfig
+
+
+@define(slots=True, repr=False)
+class TelemetryConfig(BaseConfig):
+    """Main configuration object for the Foundation Telemetry system."""
+
+    service_name: str | None = field(
+        default=None,
+        env_var="PROVIDE_SERVICE_NAME",
+        description="Service name for telemetry",
+    )
+    service_version: str | None = field(
+        default=None,
+        env_var="PROVIDE_SERVICE_VERSION",
+        description="Service version for telemetry",
+    )
+    logging: LoggingConfig = field(
+        factory=LoggingConfig, description="Logging configuration"
+    )
+    globally_disabled: bool = field(
+        default=False,
+        env_var="PROVIDE_TELEMETRY_DISABLED",
+        description="Globally disable telemetry",
+    )
+
+    # OpenTelemetry configuration
+    tracing_enabled: bool = field(
+        default=True,
+        env_var="OTEL_TRACING_ENABLED",
+        description="Enable OpenTelemetry tracing",
+    )
+    metrics_enabled: bool = field(
+        default=True,
+        env_var="OTEL_METRICS_ENABLED",
+        description="Enable OpenTelemetry metrics",
+    )
+    otlp_endpoint: str | None = field(
+        default=None,
+        env_var="OTEL_EXPORTER_OTLP_ENDPOINT",
+        description="OTLP endpoint for traces and metrics",
+    )
+    otlp_traces_endpoint: str | None = field(
+        default=None,
+        env_var="OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+        description="OTLP endpoint specifically for traces",
+    )
+    otlp_headers: str | None = field(
+        default=None,
+        env_var="OTEL_EXPORTER_OTLP_HEADERS",
+        description="Headers to send with OTLP requests (key1=value1,key2=value2)",
+    )
+    otlp_protocol: str = field(
+        default="http/protobuf",
+        env_var="OTEL_EXPORTER_OTLP_PROTOCOL",
+        description="OTLP protocol (grpc, http/protobuf)",
+    )
+    trace_sample_rate: float = field(
+        default=1.0,
+        env_var="OTEL_TRACE_SAMPLE_RATE",
+        description="Sampling rate for traces (0.0 to 1.0)",
+    )
+
+    # OpenObserve configuration
+    openobserve_url: str | None = field(
+        default=None,
+        env_var="OPENOBSERVE_URL",
+        description="OpenObserve API endpoint URL",
+    )
+    openobserve_org: str = field(
+        default="default",
+        env_var="OPENOBSERVE_ORG",
+        description="OpenObserve organization name",
+    )
+    openobserve_user: str | None = field(
+        default=None,
+        env_var="OPENOBSERVE_USER",
+        description="OpenObserve username for authentication",
+    )
+    openobserve_password: str | None = field(
+        default=None,
+        env_var="OPENOBSERVE_PASSWORD",
+        description="OpenObserve password for authentication",
+    )
+    openobserve_stream: str = field(
+        default="default",
+        env_var="OPENOBSERVE_STREAM",
+        description="Default OpenObserve stream name",
+    )
+
+    @classmethod
+    def from_env(cls, strict: bool = True) -> "TelemetryConfig":
+        """Creates a TelemetryConfig instance from environment variables."""
+        config_dict = {}
+
+        # Check OTEL_SERVICE_NAME first, then PROVIDE_SERVICE_NAME
+        service_name = os.getenv("OTEL_SERVICE_NAME") or os.getenv(
+            "PROVIDE_SERVICE_NAME"
+        )
+        if service_name:
+            config_dict["service_name"] = service_name
+
+        # Service version
+        service_version = os.getenv("OTEL_SERVICE_VERSION") or os.getenv(
+            "PROVIDE_SERVICE_VERSION"
+        )
+        if service_version:
+            config_dict["service_version"] = service_version
+
+        # Telemetry disable flag
+        if disabled := os.getenv("PROVIDE_TELEMETRY_DISABLED"):
+            config_dict["globally_disabled"] = disabled.lower() == "true"
+
+        # OpenTelemetry specific configuration
+        if tracing_enabled := os.getenv("OTEL_TRACING_ENABLED"):
+            config_dict["tracing_enabled"] = tracing_enabled.lower() == "true"
+
+        if metrics_enabled := os.getenv("OTEL_METRICS_ENABLED"):
+            config_dict["metrics_enabled"] = metrics_enabled.lower() == "true"
+
+        if otlp_endpoint := os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT"):
+            config_dict["otlp_endpoint"] = otlp_endpoint
+
+        if otlp_traces_endpoint := os.getenv("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"):
+            config_dict["otlp_traces_endpoint"] = otlp_traces_endpoint
+
+        if otlp_headers := os.getenv("OTEL_EXPORTER_OTLP_HEADERS"):
+            config_dict["otlp_headers"] = otlp_headers
+
+        if otlp_protocol := os.getenv("OTEL_EXPORTER_OTLP_PROTOCOL"):
+            config_dict["otlp_protocol"] = otlp_protocol
+
+        if trace_sample_rate := os.getenv("OTEL_TRACE_SAMPLE_RATE"):
+            try:
+                config_dict["trace_sample_rate"] = float(trace_sample_rate)
+            except ValueError:
+                if strict:
+                    raise
+                # Use default value in non-strict mode
+
+        # OpenObserve configuration
+        if openobserve_url := os.getenv("OPENOBSERVE_URL"):
+            config_dict["openobserve_url"] = openobserve_url
+
+        if openobserve_org := os.getenv("OPENOBSERVE_ORG"):
+            config_dict["openobserve_org"] = openobserve_org
+
+        if openobserve_user := os.getenv("OPENOBSERVE_USER"):
+            config_dict["openobserve_user"] = openobserve_user
+
+        if openobserve_password := os.getenv("OPENOBSERVE_PASSWORD"):
+            config_dict["openobserve_password"] = openobserve_password
+
+        if openobserve_stream := os.getenv("OPENOBSERVE_STREAM"):
+            config_dict["openobserve_stream"] = openobserve_stream
+
+        # Load logging config from env
+        config_dict["logging"] = LoggingConfig.from_env(strict=strict)
+
+        return cls(**config_dict)
+
+    def get_otlp_headers_dict(self) -> dict[str, str]:
+        """Parse OTLP headers string into dictionary.
+
+        Returns:
+            Dictionary of header key-value pairs
+        """
+        if not self.otlp_headers:
+            return {}
+
+        headers = {}
+        for pair in self.otlp_headers.split(","):
+            if "=" in pair:
+                key, value = pair.split("=", 1)
+                headers[key.strip()] = value.strip()
+        return headers