Initial curated ITWorx_MCP_Hub source from 368fba691ea8d23403b4d56b53b5ec670d7c5020

services/observability/__init__.py

@@ -0,0 +1,5 @@
+"""Health aggregation and operational telemetry service boundaries."""
+
+from .health import AggregateHealth, DependencyHealth, aggregate_health
+
+__all__ = ["AggregateHealth", "DependencyHealth", "aggregate_health"]

services/observability/health.py

@@ -0,0 +1,54 @@
+"""Safe aggregate health semantics: required failures are unhealthy, optional
+connector and Redis failures are isolated and reported as degraded."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class DependencyHealth:
+    name: str
+    status: str
+    required: bool = True
+    authoritative: bool = True
+    detail: str = ""
+
+    def payload(self) -> dict[str, Any]:
+        return {
+            "status": self.status
+            if self.status in {"healthy", "ready", "degraded", "unhealthy", "unknown"}
+            else "unknown",
+            "required": self.required,
+            "authoritative": self.authoritative,
+            "detail": self.detail[:160],
+        }
+
+
+@dataclass(frozen=True)
+class AggregateHealth:
+    status: str
+    dependencies: Mapping[str, Mapping[str, Any]]
+
+    def payload(self, *, service: str, trace_id: str) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "service": service,
+            "traceId": trace_id,
+            "dependencies": self.dependencies,
+        }
+
+
+def aggregate_health(dependencies: Iterable[DependencyHealth]) -> AggregateHealth:
+    values = list(dependencies)
+    if not values:
+        return AggregateHealth("unhealthy", {})
+    payload = {item.name: item.payload() for item in values}
+    required_failure = any(
+        item.required and item.status not in {"healthy", "ready"} for item in values
+    )
+    degraded = any(not item.required and item.status not in {"healthy", "ready"} for item in values)
+    status = "unhealthy" if required_failure else "degraded" if degraded else "healthy"
+    return AggregateHealth(status, payload)