botanu 0.1.dev60__py3-none-any.whl

botanu/sdk/config.py

@@ -0,0 +1,330 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Configuration for Botanu SDK.
+
+The SDK is intentionally minimal on the hot path. Heavy processing happens in
+the OpenTelemetry Collector, not in the application:
+
+- **SDK responsibility**: Generate run_id, propagate minimal context (run_id, workflow)
+- **Collector responsibility**: PII redaction, vendor detection, attribute enrichment
+
+Configuration precedence (highest to lowest):
+1. Code arguments (explicit values passed to BotanuConfig)
+2. Environment variables (BOTANU_*, OTEL_*)
+3. YAML config file (botanu.yaml or specified path)
+4. Built-in defaults
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BotanuConfig:
+    """Configuration for Botanu SDK and OpenTelemetry.
+
+    The SDK is a thin wrapper on OpenTelemetry.  PII redaction, cardinality
+    limits, and vendor enrichment are handled by the OTel Collector — not here.
+
+    Typically configured via environment variables (no hardcoded values)::
+
+        >>> # Reads from OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, etc.
+        >>> config = BotanuConfig()
+
+        >>> # Or load from YAML
+        >>> config = BotanuConfig.from_yaml("config/botanu.yaml")
+    """
+
+    # Service identification
+    service_name: Optional[str] = None
+    service_version: Optional[str] = None
+    service_namespace: Optional[str] = None
+    deployment_environment: Optional[str] = None
+
+    # Resource detection
+    auto_detect_resources: bool = True
+
+    # OTLP exporter configuration
+    otlp_endpoint: Optional[str] = None
+    otlp_headers: Optional[Dict[str, str]] = None
+
+    # Span export configuration
+    # Large queue prevents span loss under burst traffic.
+    # At ~1KB/span, 65536 spans ≈ 64MB memory ceiling.
+    max_export_batch_size: int = 512
+    max_queue_size: int = 65536
+    schedule_delay_millis: int = 5000
+    export_timeout_millis: int = 30000
+
+    # Propagation mode: "lean" (run_id + workflow only) or "full" (all context)
+    propagation_mode: str = "lean"
+
+    # Auto-instrumentation packages to enable
+    auto_instrument_packages: List[str] = field(
+        default_factory=lambda: [
+            # HTTP clients
+            "requests",
+            "httpx",
+            "urllib3",
+            "aiohttp_client",
+            # Web frameworks
+            "fastapi",
+            "flask",
+            "django",
+            "starlette",
+            # Databases
+            "sqlalchemy",
+            "psycopg2",
+            "asyncpg",
+            "pymongo",
+            "redis",
+            # Messaging
+            "celery",
+            "kafka_python",
+            # gRPC
+            "grpc",
+            # GenAI / AI
+            "openai_v2",
+            "anthropic",
+            "vertexai",
+            "google_genai",
+            "langchain",
+            # Runtime
+            "logging",
+        ]
+    )
+
+    # Config file path (for tracking where config was loaded from)
+    _config_file: Optional[str] = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        """Apply environment variable defaults.
+
+        Precedence: BOTANU_* > OTEL_* > defaults
+        """
+        if self.service_name is None:
+            self.service_name = os.getenv(
+                "BOTANU_SERVICE_NAME",
+                os.getenv("OTEL_SERVICE_NAME", "unknown_service"),
+            )
+
+        if self.service_version is None:
+            self.service_version = os.getenv("OTEL_SERVICE_VERSION")
+
+        if self.service_namespace is None:
+            self.service_namespace = os.getenv("OTEL_SERVICE_NAMESPACE")
+
+        env_auto_detect = os.getenv("BOTANU_AUTO_DETECT_RESOURCES")
+        if env_auto_detect is not None:
+            self.auto_detect_resources = env_auto_detect.lower() in ("true", "1", "yes")
+
+        if self.deployment_environment is None:
+            self.deployment_environment = os.getenv(
+                "BOTANU_ENVIRONMENT",
+                os.getenv("OTEL_DEPLOYMENT_ENVIRONMENT", "production"),
+            )
+
+        if self.otlp_endpoint is None:
+            # Check BOTANU_COLLECTOR_ENDPOINT first, then OTEL_* vars
+            botanu_endpoint = os.getenv("BOTANU_COLLECTOR_ENDPOINT")
+            if botanu_endpoint:
+                self.otlp_endpoint = botanu_endpoint
+            else:
+                env_endpoint = os.getenv("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")
+                if env_endpoint:
+                    self.otlp_endpoint = env_endpoint
+                else:
+                    base = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318")
+                    self.otlp_endpoint = base
+
+        env_propagation_mode = os.getenv("BOTANU_PROPAGATION_MODE")
+        if env_propagation_mode and env_propagation_mode in ("lean", "full"):
+            self.propagation_mode = env_propagation_mode
+
+        # Export tuning via env vars
+        env_queue_size = os.getenv("BOTANU_MAX_QUEUE_SIZE")
+        if env_queue_size:
+            try:
+                self.max_queue_size = int(env_queue_size)
+            except ValueError:
+                pass
+
+        env_batch_size = os.getenv("BOTANU_MAX_EXPORT_BATCH_SIZE")
+        if env_batch_size:
+            try:
+                self.max_export_batch_size = int(env_batch_size)
+            except ValueError:
+                pass
+
+        env_export_timeout = os.getenv("BOTANU_EXPORT_TIMEOUT_MILLIS")
+        if env_export_timeout:
+            try:
+                self.export_timeout_millis = int(env_export_timeout)
+            except ValueError:
+                pass
+
+    # ------------------------------------------------------------------
+    # YAML loading
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_yaml(cls, path: Optional[str] = None) -> BotanuConfig:
+        """Load configuration from a YAML file.
+
+        Supports environment variable interpolation using ``${VAR_NAME}`` syntax.
+
+        Args:
+            path: Path to YAML config file.
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist.
+            ValueError: If YAML is malformed.
+        """
+        if path is None:
+            raise FileNotFoundError("No config file path provided")
+
+        resolved = Path(path)
+        if not resolved.exists():
+            raise FileNotFoundError(f"Config file not found: {resolved}")
+
+        try:
+            import yaml  # type: ignore[import-untyped]
+        except ImportError as err:
+            raise ImportError("PyYAML required for YAML config. Install with: pip install pyyaml") from err
+
+        with open(resolved) as fh:
+            raw_content = fh.read()
+
+        content = _interpolate_env_vars(raw_content)
+
+        try:
+            data = yaml.safe_load(content)
+        except yaml.YAMLError as exc:
+            raise ValueError(f"Invalid YAML in {resolved}: {exc}") from exc
+
+        if data is None:
+            data = {}
+
+        return cls._from_dict(data, config_file=str(resolved))
+
+    @classmethod
+    def from_file_or_env(cls, path: Optional[str] = None) -> BotanuConfig:
+        """Load config from file if exists, otherwise use environment variables.
+
+        Search order:
+        1. Explicit *path* argument
+        2. ``BOTANU_CONFIG_FILE`` env var
+        3. ``./botanu.yaml``
+        4. ``./config/botanu.yaml``
+        5. Falls back to env-only config
+        """
+        search_paths: List[Path] = []
+
+        if path:
+            search_paths.append(Path(path))
+
+        env_path = os.getenv("BOTANU_CONFIG_FILE")
+        if env_path:
+            search_paths.append(Path(env_path))
+
+        search_paths.extend(
+            [
+                Path("botanu.yaml"),
+                Path("botanu.yml"),
+                Path("config/botanu.yaml"),
+                Path("config/botanu.yml"),
+            ]
+        )
+
+        for candidate in search_paths:
+            if candidate.exists():
+                logger.info("Loading config from: %s", candidate)
+                return cls.from_yaml(str(candidate))
+
+        logger.debug("No config file found, using environment variables only")
+        return cls()
+
+    @classmethod
+    def _from_dict(
+        cls,
+        data: Dict[str, Any],
+        config_file: Optional[str] = None,
+    ) -> BotanuConfig:
+        """Create config from dictionary (parsed YAML)."""
+        service = data.get("service", {})
+        otlp = data.get("otlp", {})
+        export = data.get("export", {})
+        propagation = data.get("propagation", {})
+        resource = data.get("resource", {})
+        auto_packages = data.get("auto_instrument_packages")
+
+        return cls(
+            service_name=service.get("name"),
+            service_version=service.get("version"),
+            service_namespace=service.get("namespace"),
+            deployment_environment=service.get("environment"),
+            auto_detect_resources=resource.get("auto_detect", True),
+            otlp_endpoint=otlp.get("endpoint"),
+            otlp_headers=otlp.get("headers"),
+            max_export_batch_size=export.get("batch_size", 512),
+            max_queue_size=export.get("queue_size", 65536),
+            schedule_delay_millis=export.get("delay_ms", 5000),
+            export_timeout_millis=export.get("export_timeout_ms", 30000),
+            propagation_mode=propagation.get("mode", "lean"),
+            auto_instrument_packages=(auto_packages if auto_packages else BotanuConfig().auto_instrument_packages),
+            _config_file=config_file,
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Export configuration as dictionary."""
+        return {
+            "service": {
+                "name": self.service_name,
+                "version": self.service_version,
+                "namespace": self.service_namespace,
+                "environment": self.deployment_environment,
+            },
+            "resource": {
+                "auto_detect": self.auto_detect_resources,
+            },
+            "otlp": {
+                "endpoint": self.otlp_endpoint,
+                "headers": self.otlp_headers,
+            },
+            "export": {
+                "batch_size": self.max_export_batch_size,
+                "queue_size": self.max_queue_size,
+                "delay_ms": self.schedule_delay_millis,
+                "export_timeout_ms": self.export_timeout_millis,
+            },
+            "propagation": {
+                "mode": self.propagation_mode,
+            },
+            "auto_instrument_packages": self.auto_instrument_packages,
+        }
+
+
+def _interpolate_env_vars(content: str) -> str:
+    """Interpolate ``${VAR_NAME}`` and ``${VAR_NAME:-default}`` in *content*."""
+    pattern = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}")
+
+    def _replace(match: re.Match) -> str:  # type: ignore[type-arg]
+        var_name = match.group(1)
+        default = match.group(2)
+        value = os.getenv(var_name)
+        if value is not None:
+            return value
+        if default is not None:
+            return default
+        return match.group(0)
+
+    return pattern.sub(_replace, content)

botanu/sdk/context.py

@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: 2026 The Botanu Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Context and baggage helpers for Botanu SDK.
+
+Uses OpenTelemetry Context and Baggage for propagation.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, cast
+
+from opentelemetry import baggage, trace
+from opentelemetry.context import attach, get_current
+
+
+def set_baggage(key: str, value: str) -> object:
+    """Set a baggage value and attach the new context.
+
+    Baggage is automatically propagated across service boundaries via
+    W3C Baggage header.
+
+    .. warning::
+
+        Each call pushes a new context onto the stack.  The returned token
+        **must** be passed to ``opentelemetry.context.detach()`` when the
+        scope ends, otherwise the context stack grows unboundedly (memory
+        leak in long-running processes).
+
+        For setting multiple keys, prefer building the context manually
+        and attaching once — see ``decorators.py`` for the pattern.
+
+    Args:
+        key: Baggage key (e.g., ``"botanu.run_id"``).
+        value: Baggage value.
+
+    Returns:
+        Token for detaching the context later.
+    """
+    ctx = baggage.set_baggage(key, value, context=get_current())
+    return attach(ctx)
+
+
+def get_baggage(key: str) -> Optional[str]:
+    """Get a baggage value from the current context.
+
+    Args:
+        key: Baggage key (e.g., ``"botanu.run_id"``).
+
+    Returns:
+        Baggage value or ``None`` if not set.
+    """
+    value = baggage.get_baggage(key, context=get_current())
+    return cast(Optional[str], value)
+
+
+def get_current_span() -> trace.Span:
+    """Get the current active span.
+
+    Returns:
+        Current span (may be non-recording if no span is active).
+    """
+    return trace.get_current_span()
+
+
+def get_run_id() -> Optional[str]:
+    """Get the current ``run_id`` from baggage."""
+    return get_baggage("botanu.run_id")
+
+
+def get_workflow() -> Optional[str]:
+    """Get the current ``workflow`` from baggage."""
+    return get_baggage("botanu.workflow")