nthlayer-workers 1.0.0__py3-none-any.whl

nthlayer_workers/observe/dependencies/providers/zookeeper.py

@@ -0,0 +1,399 @@
+"""
+Zookeeper dependency provider.
+
+Discovers service dependencies from Zookeeper-based service registries.
+
+Supports:
+- Curator-style service discovery (0.90 confidence)
+- Service ZNode metadata with dependencies (0.85 confidence)
+- Connection strings and endpoints (0.75 confidence)
+
+Environment variables:
+- NTHLAYER_ZOOKEEPER_HOSTS: Zookeeper connection string
+- NTHLAYER_ZOOKEEPER_ROOT: Service registry root path
+
+Requires optional dependency: kazoo
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from nthlayer_common.dependency_models import (
+    DependencyType,
+    DiscoveredDependency,
+)
+from nthlayer_common.errors import ProviderError
+from nthlayer_workers.observe.dependencies.providers.base import (
+    BaseDepProvider,
+    ProviderHealth,
+    deduplicate_dependencies,
+    infer_dependency_type,
+)
+
+# Optional kazoo import
+try:
+    from kazoo.client import KazooClient, KazooState
+    from kazoo.exceptions import NoNodeError, ZookeeperError
+
+    KAZOO_AVAILABLE = True
+except ImportError:
+    KAZOO_AVAILABLE = False
+    KazooClient = None  # type: ignore
+    KazooState = None  # type: ignore
+    NoNodeError = Exception  # type: ignore
+    ZookeeperError = Exception  # type: ignore
+
+
+class ZookeeperDepProviderError(ProviderError):
+    """Zookeeper provider error."""
+
+    pass
+
+
+@dataclass
+class ZookeeperDepProvider(BaseDepProvider):
+    """
+    Dependency provider that discovers dependencies from Zookeeper.
+
+    Queries Zookeeper znodes to find:
+    - Registered services under the root path
+    - Service instance metadata (Curator format)
+    - Explicit dependency declarations in service data
+
+    Supports Curator-style service discovery format:
+    /services/<service-name>/instances/<instance-id>
+
+    Attributes:
+        hosts: Zookeeper connection string (e.g., localhost:2181)
+        root_path: Service registry root path (default: /services)
+        timeout: Connection timeout in seconds
+        auth: Optional tuple of (scheme, credential) for auth
+    """
+
+    hosts: str = "localhost:2181"
+    root_path: str = "/services"
+    timeout: float = 30.0
+    auth: tuple[str, str] | None = None
+
+    # Private fields
+    _client: Any = field(default=None, repr=False)
+    _initialized: bool = field(default=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        """Validate kazoo is available."""
+        if not KAZOO_AVAILABLE:
+            raise ZookeeperDepProviderError(
+                "kazoo library is required for Zookeeper provider. "
+                "Install with: pip install kazoo"
+            )
+
+    @property
+    def name(self) -> str:
+        """Provider name."""
+        return "zookeeper"
+
+    def _ensure_initialized(self) -> None:
+        """Initialize Zookeeper client if not already done."""
+        if self._initialized:
+            return
+
+        if not KAZOO_AVAILABLE:
+            raise ZookeeperDepProviderError("kazoo library not available")
+
+        self._client = KazooClient(
+            hosts=self.hosts,
+            timeout=self.timeout,
+        )
+
+        if self.auth:
+            self._client.add_auth(self.auth[0], self.auth[1])
+
+        self._client.start(timeout=self.timeout)
+        self._initialized = True
+
+    async def _close(self) -> None:
+        """Close Zookeeper client."""
+        if self._client:
+            self._client.stop()
+            self._client.close()
+            self._client = None
+            self._initialized = False
+
+    def _get_service_path(self, service: str) -> str:
+        """Get the ZNode path for a service."""
+        root = self.root_path.rstrip("/")
+        return f"{root}/{service}"
+
+    def _get_instances_path(self, service: str) -> str:
+        """Get the instances path for a service."""
+        return f"{self._get_service_path(service)}/instances"
+
+    def _parse_curator_instance(self, data: bytes) -> dict[str, Any]:
+        """
+        Parse Curator ServiceInstance JSON format.
+
+        Expected format:
+        {
+            "name": "service-name",
+            "id": "instance-id",
+            "address": "10.0.0.1",
+            "port": 8080,
+            "payload": {
+                "dependencies": ["dep1", "dep2"],
+                "metadata": {...}
+            }
+        }
+
+        Args:
+            data: Raw ZNode data
+
+        Returns:
+            Parsed instance dictionary
+        """
+        try:
+            if not data:
+                return {}
+            return json.loads(data.decode("utf-8"))
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            return {}
+
+    def _parse_dependencies_from_payload(
+        self, payload: dict[str, Any]
+    ) -> list[tuple[str, DependencyType]]:
+        """
+        Parse dependencies from Curator payload.
+
+        Args:
+            payload: Instance payload dictionary
+
+        Returns:
+            List of (target_name, dep_type) tuples
+        """
+        deps: list[tuple[str, DependencyType]] = []
+
+        # Check for explicit dependencies list
+        dependencies = payload.get("dependencies", [])
+        if isinstance(dependencies, str):
+            dependencies = [d.strip() for d in dependencies.split(",")]
+
+        for dep in dependencies:
+            if dep:
+                deps.append((dep, infer_dependency_type(dep)))
+
+        # Check for typed dependencies
+        for dep_type, key in [
+            (DependencyType.DATASTORE, "databases"),
+            (DependencyType.QUEUE, "queues"),
+            (DependencyType.EXTERNAL, "external"),
+        ]:
+            type_deps = payload.get(key, [])
+            if isinstance(type_deps, str):
+                type_deps = [d.strip() for d in type_deps.split(",")]
+            for dep in type_deps:
+                if dep:
+                    deps.append((dep, dep_type))
+
+        return deps
+
+    async def discover(self, service: str) -> list[DiscoveredDependency]:
+        """
+        Discover upstream dependencies for a service.
+
+        Reads service instances from Zookeeper and extracts dependencies
+        from the Curator-style payload.
+
+        Args:
+            service: Service name to find dependencies for
+
+        Returns:
+            List of discovered dependencies
+        """
+        self._ensure_initialized()
+        deps: list[DiscoveredDependency] = []
+
+        try:
+            # Check if service exists
+            service_path = self._get_service_path(service)
+            if not self._client.exists(service_path):
+                return deps
+
+            # Try to read service-level metadata first
+            data, _ = self._client.get(service_path)
+            if data:
+                service_data = self._parse_curator_instance(data)
+                payload = service_data.get("payload", service_data)
+                payload_deps = self._parse_dependencies_from_payload(payload)
+                for target, dep_type in payload_deps:
+                    deps.append(
+                        DiscoveredDependency(
+                            source_service=service,
+                            target_service=target,
+                            provider=self.name,
+                            dep_type=dep_type,
+                            confidence=0.85,
+                            metadata={
+                                "source": "service_znode",
+                                "path": service_path,
+                            },
+                            raw_source=service,
+                            raw_target=target,
+                        )
+                    )
+
+            # Try to read instance-level metadata
+            instances_path = self._get_instances_path(service)
+            if self._client.exists(instances_path):
+                instances = self._client.get_children(instances_path)
+                for instance_id in instances:
+                    instance_path = f"{instances_path}/{instance_id}"
+                    data, _ = self._client.get(instance_path)
+                    instance_data = self._parse_curator_instance(data)
+
+                    # Extract dependencies from payload
+                    payload = instance_data.get("payload", {})
+                    payload_deps = self._parse_dependencies_from_payload(payload)
+
+                    for target, dep_type in payload_deps:
+                        deps.append(
+                            DiscoveredDependency(
+                                source_service=service,
+                                target_service=target,
+                                provider=self.name,
+                                dep_type=dep_type,
+                                confidence=0.90,
+                                metadata={
+                                    "source": "curator_instance",
+                                    "instance_id": instance_id,
+                                    "path": instance_path,
+                                },
+                                raw_source=service,
+                                raw_target=target,
+                            )
+                        )
+
+        except NoNodeError:
+            pass
+        except ZookeeperError as e:
+            raise ZookeeperDepProviderError(f"Zookeeper error: {e}") from e
+
+        return deduplicate_dependencies(deps)
+
+    async def list_services(self) -> list[str]:
+        """
+        List all services in Zookeeper registry.
+
+        Returns:
+            List of service names
+        """
+        self._ensure_initialized()
+
+        try:
+            root = self.root_path.rstrip("/")
+            if not self._client.exists(root):
+                return []
+
+            children = self._client.get_children(root)
+            # Filter out non-service znodes (like "instances" paths at wrong level)
+            services = [
+                child for child in children if not child.startswith("_") and child != "instances"
+            ]
+            return sorted(services)
+
+        except NoNodeError:
+            return []
+        except ZookeeperError as e:
+            raise ZookeeperDepProviderError(f"Zookeeper error: {e}") from e
+
+    async def health_check(self) -> ProviderHealth:
+        """
+        Check Zookeeper connectivity.
+
+        Returns:
+            Provider health status
+        """
+        if not KAZOO_AVAILABLE:
+            return ProviderHealth(
+                healthy=False,
+                message="kazoo library not installed",
+            )
+
+        try:
+            self._ensure_initialized()
+
+            # Check if connected
+            state = self._client.state
+            if state == KazooState.CONNECTED:
+                return ProviderHealth(
+                    healthy=True,
+                    message=f"Connected to Zookeeper at {self.hosts}",
+                )
+            else:
+                return ProviderHealth(
+                    healthy=False,
+                    message=f"Zookeeper state: {state}",
+                )
+
+        except ZookeeperError as e:
+            return ProviderHealth(
+                healthy=False,
+                message=f"Zookeeper error: {e}",
+            )
+        except Exception as e:
+            return ProviderHealth(
+                healthy=False,
+                message=f"Connection failed: {e}",
+            )
+
+    async def get_service_attributes(self, service: str) -> dict[str, Any]:
+        """
+        Get service attributes from Zookeeper.
+
+        Args:
+            service: Service name
+
+        Returns:
+            Dictionary of attributes
+        """
+        self._ensure_initialized()
+
+        try:
+            service_path = self._get_service_path(service)
+            if not self._client.exists(service_path):
+                return {}
+
+            # Get service znode data
+            data, stat = self._client.get(service_path)
+            service_data = self._parse_curator_instance(data)
+
+            # Get instance count
+            instances_path = self._get_instances_path(service)
+            instance_count = 0
+            instances: list[dict[str, Any]] = []
+
+            if self._client.exists(instances_path):
+                instance_ids = self._client.get_children(instances_path)
+                instance_count = len(instance_ids)
+
+                # Get first instance details
+                if instance_ids:
+                    first_instance_path = f"{instances_path}/{instance_ids[0]}"
+                    instance_data, _ = self._client.get(first_instance_path)
+                    instances.append(self._parse_curator_instance(instance_data))
+
+            return {
+                "name": service_data.get("name", service),
+                "path": service_path,
+                "instance_count": instance_count,
+                "instances": instances,
+                "metadata": service_data.get("payload", {}).get("metadata", {}),
+                "created": stat.created if stat else None,
+                "modified": stat.last_modified if stat else None,
+            }
+
+        except NoNodeError:
+            return {}
+        except ZookeeperError as e:
+            raise ZookeeperDepProviderError(f"Zookeeper error: {e}") from e

nthlayer_workers/observe/deployments/__init__.py

@@ -0,0 +1 @@
+"""Deployment event handling."""

nthlayer_workers/observe/discovery/__init__.py

@@ -0,0 +1,14 @@
+"""Metric and service discovery."""
+
+from nthlayer_workers.observe.discovery.classifier import MetricClassifier
+from nthlayer_workers.observe.discovery.client import MetricDiscoveryClient
+from nthlayer_workers.observe.discovery.models import DiscoveredMetric, DiscoveryResult, MetricType, TechnologyGroup
+
+__all__ = [
+    "MetricDiscoveryClient",
+    "MetricClassifier",
+    "DiscoveredMetric",
+    "DiscoveryResult",
+    "MetricType",
+    "TechnologyGroup",
+]

nthlayer_workers/observe/discovery/classifier.py

@@ -0,0 +1,66 @@
+"""Metric classifier for technology and type detection."""
+
+from __future__ import annotations
+
+import re
+
+from nthlayer_workers.observe.discovery.models import DiscoveredMetric, MetricType, TechnologyGroup
+
+
+class MetricClassifier:
+    """Classifies metrics by technology using pattern matching."""
+
+    TECHNOLOGY_PATTERNS = [
+        (r"^pg_", TechnologyGroup.POSTGRESQL),
+        (r"postgres", TechnologyGroup.POSTGRESQL),
+        (r"^redis_", TechnologyGroup.REDIS),
+        (r"cache_hits", TechnologyGroup.REDIS),
+        (r"cache_misses", TechnologyGroup.REDIS),
+        (r"^mongodb_", TechnologyGroup.MONGODB),
+        (r"^mongo_", TechnologyGroup.MONGODB),
+        (r"^kafka_", TechnologyGroup.KAFKA),
+        (r"^mysql_", TechnologyGroup.MYSQL),
+        (r"^rabbitmq_", TechnologyGroup.RABBITMQ),
+        (r"^kube_", TechnologyGroup.KUBERNETES),
+        (r"^container_", TechnologyGroup.KUBERNETES),
+        (r"_pod_", TechnologyGroup.KUBERNETES),
+        (r"^ecs_", TechnologyGroup.KUBERNETES),
+        (r"^http_", TechnologyGroup.HTTP),
+        (r"_request", TechnologyGroup.HTTP),
+        (r"_response", TechnologyGroup.HTTP),
+    ]
+
+    TYPE_PATTERNS = [
+        (r"_total$", MetricType.COUNTER),
+        (r"_count$", MetricType.COUNTER),
+        (r"_created$", MetricType.COUNTER),
+        (r"_bucket$", MetricType.HISTOGRAM),
+        (r"_sum$", MetricType.SUMMARY),
+        (r"_seconds_", MetricType.HISTOGRAM),
+        (r"_bytes", MetricType.GAUGE),
+        (r"_ratio$", MetricType.GAUGE),
+        (r"_percentage$", MetricType.GAUGE),
+    ]
+
+    def classify(self, metric: DiscoveredMetric) -> DiscoveredMetric:
+        """Classify a discovered metric by technology and type."""
+        metric.technology = self._classify_technology(metric.name)
+
+        if metric.type == MetricType.UNKNOWN:
+            metric.type = self._infer_type(metric.name)
+
+        return metric
+
+    def _classify_technology(self, metric_name: str) -> TechnologyGroup:
+        metric_lower = metric_name.lower()
+        for pattern, technology in self.TECHNOLOGY_PATTERNS:
+            if re.search(pattern, metric_lower):
+                return technology
+        return TechnologyGroup.CUSTOM
+
+    def _infer_type(self, metric_name: str) -> MetricType:
+        metric_lower = metric_name.lower()
+        for pattern, metric_type in self.TYPE_PATTERNS:
+            if re.search(pattern, metric_lower):
+                return metric_type
+        return MetricType.GAUGE

nthlayer_workers/observe/discovery/client.py

@@ -0,0 +1,189 @@
+"""Prometheus metric discovery client."""
+
+from __future__ import annotations
+
+import re
+
+import httpx
+import structlog
+
+from nthlayer_workers.observe.discovery.classifier import MetricClassifier
+from nthlayer_workers.observe.discovery.models import DiscoveredMetric, DiscoveryResult, MetricType, TechnologyGroup
+
+logger = structlog.get_logger()
+
+
+class MetricDiscoveryClient:
+    """Client for discovering metrics from Prometheus."""
+
+    def __init__(
+        self,
+        prometheus_url: str,
+        username: str | None = None,
+        password: str | None = None,
+        bearer_token: str | None = None,
+    ):
+        self.prometheus_url = prometheus_url.rstrip("/")
+        self.auth = (username, password) if username and password else None
+        self.headers = {"Authorization": f"Bearer {bearer_token}"} if bearer_token else {}
+        self.classifier = MetricClassifier()
+
+    def discover(self, selector: str) -> DiscoveryResult:
+        """Discover all metrics matching the given selector."""
+        metric_names = self._get_metric_names(selector)
+
+        metrics = []
+        for name in metric_names:
+            metric = self._discover_metric(name, selector)
+            if metric:
+                metrics.append(metric)
+
+        classified_metrics = [self.classifier.classify(m) for m in metrics]
+
+        result = DiscoveryResult(
+            service=self._extract_service_from_selector(selector),
+            total_metrics=len(classified_metrics),
+            metrics=classified_metrics,
+        )
+
+        for metric in classified_metrics:
+            tech = metric.technology.value if isinstance(metric.technology, TechnologyGroup) else metric.technology
+            if tech not in result.metrics_by_technology:
+                result.metrics_by_technology[tech] = []
+            result.metrics_by_technology[tech].append(metric)
+
+        for metric in classified_metrics:
+            mtype = metric.type.value if isinstance(metric.type, MetricType) else metric.type
+            if mtype not in result.metrics_by_type:
+                result.metrics_by_type[mtype] = []
+            result.metrics_by_type[mtype].append(metric)
+
+        return result
+
+    def _get_metric_names(self, selector: str) -> list[str]:
+        """Query Prometheus for all metric names matching selector."""
+        url = f"{self.prometheus_url}/api/v1/series"
+        params = {"match[]": selector}
+
+        if "/metrics" in self.prometheus_url or "fly.dev" in self.prometheus_url:
+            return self._get_metrics_from_endpoint(selector)
+
+        try:
+            response = httpx.get(
+                url, params=params, auth=self.auth, headers=self.headers, timeout=30
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            if data.get("status") != "success":
+                return []
+
+            metric_names = set()
+            for series in data.get("data", []):
+                if "__name__" in series:
+                    metric_names.add(series["__name__"])
+
+            return sorted(metric_names)
+
+        except Exception as e:
+            logger.warning("prometheus_series_query_failed", error=str(e))
+            return []
+
+    def _discover_metric(self, metric_name: str, selector: str) -> DiscoveredMetric | None:
+        """Discover detailed information about a specific metric."""
+        metadata = self._get_metric_metadata(metric_name)
+        labels = self._get_label_values(metric_name, selector)
+
+        return DiscoveredMetric(
+            name=metric_name,
+            type=MetricType(metadata.get("type", "unknown")),
+            technology=TechnologyGroup.UNKNOWN,
+            help_text=metadata.get("help"),
+            labels=labels,
+        )
+
+    def _get_metric_metadata(self, metric_name: str) -> dict:
+        """Query Prometheus metadata API for metric type and help text."""
+        url = f"{self.prometheus_url}/api/v1/metadata"
+        params = {"metric": metric_name}
+
+        try:
+            response = httpx.get(
+                url, params=params, auth=self.auth, headers=self.headers, timeout=10
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            if data.get("status") == "success":
+                metric_data = data.get("data", {}).get(metric_name, [])
+                if metric_data:
+                    return metric_data[0]
+
+            return {}
+
+        except Exception:
+            return {}
+
+    def _get_label_values(self, metric_name: str, selector: str) -> dict[str, list[str]]:
+        """Get all label values for a metric."""
+        url = f"{self.prometheus_url}/api/v1/series"
+        full_selector = f"{metric_name}{selector}"
+        params = {"match[]": full_selector}
+
+        try:
+            response = httpx.get(
+                url, params=params, auth=self.auth, headers=self.headers, timeout=10
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            if data.get("status") != "success":
+                return {}
+
+            labels: dict[str, set] = {}
+            for series in data.get("data", []):
+                for label, value in series.items():
+                    if label == "__name__":
+                        continue
+                    if label not in labels:
+                        labels[label] = set()
+                    labels[label].add(value)
+
+            return {k: sorted(v) for k, v in labels.items()}
+
+        except Exception:
+            return {}
+
+    def _get_metrics_from_endpoint(self, selector: str) -> list[str]:
+        """Parse /metrics endpoint directly (fallback for non-Prometheus targets)."""
+        service = self._extract_service_from_selector(selector)
+        url = f"{self.prometheus_url}/metrics"
+        filter_by_service = service and service != "unknown"
+
+        try:
+            response = httpx.get(url, auth=self.auth, headers=self.headers, timeout=30)
+            response.raise_for_status()
+
+            metric_names = set()
+            for line in response.text.split("\n"):
+                if not line or line.startswith("#"):
+                    continue
+
+                if filter_by_service and f'service="{service}"' not in line:
+                    continue
+
+                if "{" in line:
+                    metric_names.add(line.split("{")[0])
+                elif " " in line:
+                    metric_names.add(line.split(" ")[0])
+
+            return sorted(metric_names)
+
+        except Exception as e:
+            logger.warning("metrics_endpoint_parse_failed", error=str(e))
+            return []
+
+    def _extract_service_from_selector(self, selector: str) -> str:
+        """Extract service name from selector string."""
+        match = re.search(r'service="([^"]+)"', selector)
+        return match.group(1) if match else "unknown"