svc-infra 0.1.603__tar.gz → 0.1.604__tar.gz

{svc_infra-0.1.603 → svc_infra-0.1.604}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: svc-infra
-Version: 0.1.603
+Version: 0.1.604
 Summary: Infrastructure for building and deploying prod-ready services
 License: MIT
 Keywords: fastapi,sqlalchemy,alembic,auth,infra,async,pydantic
@@ -91,6 +91,7 @@ svc-infra packages the shared building blocks we use to ship production FastAPI
 | Jobs | JobQueue, scheduler, CLI worker | [Jobs quickstart](docs/jobs.md) |
 | Cache | cashews decorators, namespace management, TTL helpers | [Cache guide](docs/cache.md) |
 | Observability | Prometheus middleware, Grafana automation, OTEL hooks | [Observability guide](docs/observability.md) |
+| Ops | Probes, breaker, SLOs & dashboards | [SLOs & Ops](docs/ops.md) |
 | Webhooks | Subscription store, signing, retry worker | [Webhooks framework](docs/webhooks.md) |
 | Security | Password policy, lockout, signed cookies, headers | [Security hardening](docs/security.md) |
 | Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](docs/data-lifecycle.md) |

{svc_infra-0.1.603 → svc_infra-0.1.604}/README.md

@@ -15,6 +15,7 @@ svc-infra packages the shared building blocks we use to ship production FastAPI
 | Jobs | JobQueue, scheduler, CLI worker | [Jobs quickstart](docs/jobs.md) |
 | Cache | cashews decorators, namespace management, TTL helpers | [Cache guide](docs/cache.md) |
 | Observability | Prometheus middleware, Grafana automation, OTEL hooks | [Observability guide](docs/observability.md) |
+| Ops | Probes, breaker, SLOs & dashboards | [SLOs & Ops](docs/ops.md) |
 | Webhooks | Subscription store, signing, retry worker | [Webhooks framework](docs/webhooks.md) |
 | Security | Password policy, lockout, signed cookies, headers | [Security hardening](docs/security.md) |
 | Data Lifecycle | Fixtures, retention, erasure, backups | [Data lifecycle](docs/data-lifecycle.md) |

{svc_infra-0.1.603 → svc_infra-0.1.604}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "svc-infra"
-version = "0.1.603"
+version = "0.1.604"
 description = "Infrastructure for building and deploying prod-ready services"
 authors = ["Ali Khatami <aliikhatami94@gmail.com>"]
 license = "MIT"
@@ -128,6 +128,7 @@ markers = [
     "webhooks: Webhooks framework tests",
     "tenancy: Tenancy isolation and enforcement tests",
     "data_lifecycle: Data lifecycle (fixtures, retention, erasure, backups)",
+    "ops: SLOs & Ops tests (probes, breaker, instrumentation)",
 ]
 filterwarnings = [
     "ignore:The `route` decorator is deprecated:DeprecationWarning:starlette.*",

svc_infra-0.1.604/src/svc_infra/obs/add.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Iterable, Optional, Protocol
+
+from svc_infra.obs.settings import ObservabilitySettings
+
+
+def _want_metrics(cfg: ObservabilitySettings) -> bool:
+    return bool(cfg.METRICS_ENABLED)
+
+
+class RouteClassifier(Protocol):
+    def __call__(
+        self, route_path: str, method: str
+    ) -> str:  # e.g., returns "public|internal|admin"
+        ...
+
+
+def add_observability(
+    app: Any | None = None,
+    *,
+    db_engines: Optional[Iterable[Any]] = None,
+    metrics_path: str | None = None,
+    skip_metric_paths: Optional[Iterable[str]] = None,
+    route_classifier: RouteClassifier | None = None,
+) -> Callable[[], None]:
+    """
+    Enable Prometheus metrics for the ASGI app and optional SQLAlchemy pool metrics.
+    Returns a no-op shutdown callable for API compatibility.
+    """
+    cfg = ObservabilitySettings()
+
+    # --- Metrics (Prometheus) — import lazily so CLIs/tests don’t require prometheus_client
+    if app is not None and _want_metrics(cfg):
+        try:
+            from svc_infra.obs.metrics.asgi import (  # lazy
+                PrometheusMiddleware,
+                add_prometheus,
+                metrics_endpoint,
+            )
+
+            path = metrics_path or cfg.METRICS_PATH
+            skip_paths = tuple(skip_metric_paths or (path, "/health", "/healthz"))
+            # If a route_classifier is provided, use a custom route_resolver to append class label
+            if route_classifier is None:
+                add_prometheus(
+                    app,
+                    path=path,
+                    skip_paths=skip_paths,
+                )
+            else:
+                # Install middleware manually to pass route_resolver
+                def _resolver(req):
+                    # Base template
+                    from svc_infra.obs.metrics.asgi import _route_template  # type: ignore
+
+                    base = _route_template(req)
+                    method = getattr(req, "method", "GET")
+                    cls = route_classifier(base, method)
+                    # Encode as base|class for downstream label splitting in dashboards
+                    return f"{base}|{cls}"
+
+                app.add_middleware(
+                    PrometheusMiddleware,
+                    skip_paths=skip_paths,
+                    route_resolver=_resolver,
+                )
+                # Mount /metrics endpoint without re-adding middleware
+                try:
+                    from svc_infra.api.fastapi.dual.public import public_router
+                    from svc_infra.app.env import CURRENT_ENVIRONMENT, DEV_ENV, LOCAL_ENV
+
+                    router = public_router()
+                    router.add_api_route(
+                        path,
+                        endpoint=metrics_endpoint(),
+                        include_in_schema=CURRENT_ENVIRONMENT in (LOCAL_ENV, DEV_ENV),
+                        tags=["observability"],
+                    )
+                    app.include_router(router)
+                except Exception:
+                    app.add_route(path, metrics_endpoint())
+        except Exception:
+            pass
+
+    # --- DB pool metrics (best effort) — also lazy
+    if db_engines:
+        try:
+            from svc_infra.obs.metrics.sqlalchemy import bind_sqlalchemy_pool_metrics  # lazy
+
+            for eng in db_engines:
+                try:
+                    bind_sqlalchemy_pool_metrics(eng)
+                except Exception:
+                    pass
+        except Exception:
+            pass
+
+    # --- HTTP client metrics (best effort) — import lazily
+    try:
+        from svc_infra.obs.metrics.http import instrument_httpx, instrument_requests  # lazy
+
+        try:
+            instrument_requests()
+        except Exception:
+            pass
+        try:
+            instrument_httpx()
+        except Exception:
+            pass
+    except Exception:
+        pass
+
+    # Tracing removed; return no-op for backward compatibility
+    return lambda: None

svc_infra-0.1.604/src/svc_infra/obs/grafana/dashboards/http-overview.json

@@ -0,0 +1,45 @@
+{
+  "title": "Service HTTP Overview",
+  "tags": ["svc-infra", "http"],
+  "timezone": "browser",
+  "panels": [
+    {
+      "type": "timeseries",
+      "title": "Success Rate (5m)",
+      "targets": [
+        {
+          "expr": "sum(rate(http_server_requests_total{code!~\"5..\"}[5m])) / sum(rate(http_server_requests_total[5m]))",
+          "legendFormat": "success_rate"
+        }
+      ]
+    },
+    {
+      "type": "timeseries",
+      "title": "Latency p99",
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.99, sum(rate(http_server_request_duration_seconds_bucket[5m])) by (le))",
+          "legendFormat": "p99"
+        }
+      ]
+    },
+    {
+      "type": "table",
+      "title": "Top Routes by Error (5m)",
+      "targets": [
+        {
+          "expr": "topk(10, sum(rate(http_server_requests_total{code=~\"5..\"}[5m])) by (route))",
+          "legendFormat": "{{route}}"
+        }
+      ]
+    }
+  ],
+  "templating": {
+    "list": []
+  },
+  "time": {
+    "from": "now-6h",
+    "to": "now"
+  },
+  "refresh": "30s"
+}

svc_infra-0.1.603/src/svc_infra/obs/add.py

@@ -1,68 +0,0 @@
-from __future__ import annotations
-
-from typing import Any, Callable, Iterable, Optional
-
-from svc_infra.obs.settings import ObservabilitySettings
-
-
-def _want_metrics(cfg: ObservabilitySettings) -> bool:
-    return bool(cfg.METRICS_ENABLED)
-
-
-def add_observability(
-    app: Any | None = None,
-    *,
-    db_engines: Optional[Iterable[Any]] = None,
-    metrics_path: str | None = None,
-    skip_metric_paths: Optional[Iterable[str]] = None,
-) -> Callable[[], None]:
-    """
-    Enable Prometheus metrics for the ASGI app and optional SQLAlchemy pool metrics.
-    Returns a no-op shutdown callable for API compatibility.
-    """
-    cfg = ObservabilitySettings()
-
-    # --- Metrics (Prometheus) — import lazily so CLIs/tests don’t require prometheus_client
-    if app is not None and _want_metrics(cfg):
-        try:
-            from svc_infra.obs.metrics.asgi import add_prometheus  # lazy
-
-            path = metrics_path or cfg.METRICS_PATH
-            add_prometheus(
-                app,
-                path=path,
-                skip_paths=tuple(skip_metric_paths or (path, "/health", "/healthz")),
-            )
-        except Exception:
-            pass
-
-    # --- DB pool metrics (best effort) — also lazy
-    if db_engines:
-        try:
-            from svc_infra.obs.metrics.sqlalchemy import bind_sqlalchemy_pool_metrics  # lazy
-
-            for eng in db_engines:
-                try:
-                    bind_sqlalchemy_pool_metrics(eng)
-                except Exception:
-                    pass
-        except Exception:
-            pass
-
-    # --- HTTP client metrics (best effort) — import lazily
-    try:
-        from svc_infra.obs.metrics.http import instrument_httpx, instrument_requests  # lazy
-
-        try:
-            instrument_requests()
-        except Exception:
-            pass
-        try:
-            instrument_httpx()
-        except Exception:
-            pass
-    except Exception:
-        pass
-
-    # Tracing removed; return no-op for backward compatibility
-    return lambda: None