juniper-observability 0.1.0a0__tar.gz

juniper_observability-0.1.0a0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: juniper-observability
+Version: 0.1.0a0
+Summary: Shared observability primitives (health models, logging, middleware, Sentry, Prometheus) for the Juniper ML platform
+Author: Paul Calnon
+License: MIT
+Project-URL: Homepage, https://github.com/pcalnon/juniper-ml
+Project-URL: Repository, https://github.com/pcalnon/juniper-ml
+Project-URL: Issues, https://github.com/pcalnon/juniper-ml/issues
+Keywords: juniper,observability,health,metrics,logging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: starlette>=0.27
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.20.0; extra == "prometheus"
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk[fastapi]>=2.0.0; extra == "sentry"
+Provides-Extra: all
+Requires-Dist: juniper-observability[prometheus,sentry]; extra == "all"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Requires-Dist: fastapi>=0.110; extra == "test"
+Requires-Dist: prometheus-client>=0.20.0; extra == "test"
+Requires-Dist: sentry-sdk[fastapi]>=2.0.0; extra == "test"
+
+# juniper-observability
+
+Shared observability primitives for the Juniper ML platform.
+
+## What's in here
+
+- **Health models** (`DependencyStatus`, `ReadinessResponse`) — Pydantic models for the standard `/v1/health/ready` response shape used by every Juniper server.
+- **Probe utility** (`probe_dependency`) — synchronous HTTP health-check helper.
+- **Logging** (`JuniperJsonFormatter`, `configure_logging`) — structured-JSON logging with `request_id` propagation.
+- **Middleware** (`RequestIdMiddleware`, `PrometheusMiddleware`) — Starlette middlewares applied by every Juniper server. The Prometheus middleware bounds label cardinality per the R1.1 contract.
+- **Constants** (`UNMATCHED_ENDPOINT_LABEL`, `READINESS_HEADER`, `LIVENESS_TICK_BUDGET_MS`, `LIVENESS_STALENESS_SECONDS`) — pinned values from the R1.1, R1.2, and R1.3 cross-service contracts.
+- **Prometheus utilities** (`get_prometheus_app`, `set_build_info`).
+- **Sentry init** (`configure_sentry`) — with the SEC-10 `before_send` hook always installed.
+
+## Install
+
+```bash
+pip install juniper-observability                          # core only
+pip install "juniper-observability[prometheus]"            # + Prometheus middleware/utilities
+pip install "juniper-observability[sentry]"                # + Sentry init
+pip install "juniper-observability[all]"                   # everything
+```
+
+## Per-service metrics stay in each repo
+
+This package intentionally exposes only **cross-cutting** observability infrastructure. Service-specific metric definitions (training-loop counters, dataset-gen histograms, websocket gauges, etc.) live in their owning repo and use the lazy-init pattern with `prometheus_client` directly.
+
+## Design + migration
+
+See [`notes/code-review/METRICS_MONITORING_R2.1_SHARED_OBSERVABILITY_DESIGN_2026-04-28.md`](../notes/code-review/METRICS_MONITORING_R2.1_SHARED_OBSERVABILITY_DESIGN_2026-04-28.md) in the parent juniper-ml repo for the full design and the 5-PR migration sequence.
+
+## License
+
+MIT — see [LICENSE](../LICENSE).

juniper_observability-0.1.0a0/README.md

@@ -0,0 +1,34 @@
+# juniper-observability
+
+Shared observability primitives for the Juniper ML platform.
+
+## What's in here
+
+- **Health models** (`DependencyStatus`, `ReadinessResponse`) — Pydantic models for the standard `/v1/health/ready` response shape used by every Juniper server.
+- **Probe utility** (`probe_dependency`) — synchronous HTTP health-check helper.
+- **Logging** (`JuniperJsonFormatter`, `configure_logging`) — structured-JSON logging with `request_id` propagation.
+- **Middleware** (`RequestIdMiddleware`, `PrometheusMiddleware`) — Starlette middlewares applied by every Juniper server. The Prometheus middleware bounds label cardinality per the R1.1 contract.
+- **Constants** (`UNMATCHED_ENDPOINT_LABEL`, `READINESS_HEADER`, `LIVENESS_TICK_BUDGET_MS`, `LIVENESS_STALENESS_SECONDS`) — pinned values from the R1.1, R1.2, and R1.3 cross-service contracts.
+- **Prometheus utilities** (`get_prometheus_app`, `set_build_info`).
+- **Sentry init** (`configure_sentry`) — with the SEC-10 `before_send` hook always installed.
+
+## Install
+
+```bash
+pip install juniper-observability                          # core only
+pip install "juniper-observability[prometheus]"            # + Prometheus middleware/utilities
+pip install "juniper-observability[sentry]"                # + Sentry init
+pip install "juniper-observability[all]"                   # everything
+```
+
+## Per-service metrics stay in each repo
+
+This package intentionally exposes only **cross-cutting** observability infrastructure. Service-specific metric definitions (training-loop counters, dataset-gen histograms, websocket gauges, etc.) live in their owning repo and use the lazy-init pattern with `prometheus_client` directly.
+
+## Design + migration
+
+See [`notes/code-review/METRICS_MONITORING_R2.1_SHARED_OBSERVABILITY_DESIGN_2026-04-28.md`](../notes/code-review/METRICS_MONITORING_R2.1_SHARED_OBSERVABILITY_DESIGN_2026-04-28.md) in the parent juniper-ml repo for the full design and the 5-PR migration sequence.
+
+## License
+
+MIT — see [LICENSE](../LICENSE).

juniper_observability-0.1.0a0/juniper_observability/__init__.py

@@ -0,0 +1,65 @@
+"""``juniper-observability`` — shared observability primitives for Juniper services.
+
+Single source of truth for ``DependencyStatus`` / ``ReadinessResponse``
+Pydantic models, the dependency-probe utility, structured-JSON logging,
+the R1.1/R1.2/R1.3 contract constants, and the Starlette middlewares
+(``RequestIdMiddleware``, ``PrometheusMiddleware``) that every Juniper
+server applies.
+
+Per-service metric definitions (training-loop counters, dataset-gen
+histograms, websocket gauges, etc.) intentionally stay in their owning
+repo — only cross-cutting infrastructure lives here.
+
+See ``notes/code-review/METRICS_MONITORING_R2.1_SHARED_OBSERVABILITY_DESIGN_2026-04-28.md``
+in juniper-ml for the design and migration plan.
+"""
+
+from juniper_observability._version import __version__
+from juniper_observability.constants import (
+    HEADER_X_REQUEST_ID,
+    LIVENESS_STALENESS_SECONDS,
+    LIVENESS_TICK_BUDGET_MS,
+    READINESS_HEADER,
+    UNMATCHED_ENDPOINT_LABEL,
+)
+from juniper_observability.health.models import DependencyStatus, ReadinessResponse
+from juniper_observability.health.probe import probe_dependency
+from juniper_observability.logging import (
+    DEFAULT_LOG_FORMAT_PLAIN,
+    LOG_FORMAT_JSON,
+    JuniperJsonFormatter,
+    configure_logging,
+)
+from juniper_observability.middleware import PrometheusMiddleware, RequestIdMiddleware, request_id_var
+from juniper_observability.prometheus import get_prometheus_app, set_build_info
+from juniper_observability.sentry import DEFAULT_SENTRY_TRACES_SAMPLE_RATE, configure_sentry
+
+__all__ = [
+    # Version
+    "__version__",
+    # Constants (R1.1/R1.2/R1.3 contract)
+    "HEADER_X_REQUEST_ID",
+    "LIVENESS_STALENESS_SECONDS",
+    "LIVENESS_TICK_BUDGET_MS",
+    "READINESS_HEADER",
+    "UNMATCHED_ENDPOINT_LABEL",
+    # Health
+    "DependencyStatus",
+    "ReadinessResponse",
+    "probe_dependency",
+    # Logging
+    "DEFAULT_LOG_FORMAT_PLAIN",
+    "JuniperJsonFormatter",
+    "LOG_FORMAT_JSON",
+    "configure_logging",
+    # Middleware
+    "PrometheusMiddleware",
+    "RequestIdMiddleware",
+    "request_id_var",
+    # Prometheus utilities
+    "get_prometheus_app",
+    "set_build_info",
+    # Sentry
+    "DEFAULT_SENTRY_TRACES_SAMPLE_RATE",
+    "configure_sentry",
+]

juniper_observability-0.1.0a0/juniper_observability/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "0.1.0a0"

juniper_observability-0.1.0a0/juniper_observability/constants.py

@@ -0,0 +1,42 @@
+"""Cross-service observability contract constants.
+
+These constants pin down the wire format established by METRICS-MON
+R1.1, R1.2, and R1.3 across juniper-data, juniper-cascor, and
+juniper-canopy. Pulling them into a single module ensures that any
+future contract change happens in one place and ripples to every
+consumer at version-bump time.
+
+References:
+- juniper-ml notes/code-review/METRICS_MONITORING_R1.1_*: cardinality
+- juniper-ml notes/code-review/METRICS_MONITORING_R1.2_PROBE_DESIGN_2026-04-27.md
+- juniper-ml notes/code-review/METRICS_MONITORING_R1.3_WORKER_HEARTBEAT_DESIGN_2026-04-27.md
+"""
+
+from typing import Final
+
+# METRICS-MON R1.1 / seed-01: when a request does not match any
+# registered Starlette route template, the Prometheus middleware emits
+# this single bucket value for the ``endpoint`` label and increments a
+# separate ``http_unmatched_requests_total{method}`` counter so the
+# label cardinality stays bounded under attacker-controlled paths.
+UNMATCHED_ENDPOINT_LABEL: Final[str] = "_unmatched"
+
+# METRICS-MON R1.2 / seed-02: response header that mirrors the readiness
+# body status. Lets ``kubectl describe pod`` and ``curl -I`` surface the
+# state without parsing JSON.
+READINESS_HEADER: Final[str] = "X-Juniper-Readiness"
+
+# METRICS-MON R1.2 / seed-03: liveness tick must complete within this
+# wall-clock budget (milliseconds). Helm ``timeoutSeconds`` (5–10s)
+# wraps this with headroom; the budget catches event-loop stalls and
+# CPU starvation that the previous no-op probe could not.
+LIVENESS_TICK_BUDGET_MS: Final[int] = 250
+
+# METRICS-MON R1.2 / seed-03: heartbeat staleness threshold for
+# services that bump a per-second liveness counter (e.g.,
+# juniper-cascor's lifecycle manager). A staleness > 30s reliably
+# indicates a wedged process.
+LIVENESS_STALENESS_SECONDS: Final[float] = 30.0
+
+# Standard request-id header propagated through ``RequestIdMiddleware``.
+HEADER_X_REQUEST_ID: Final[str] = "X-Request-ID"

juniper_observability-0.1.0a0/juniper_observability/health/__init__.py

@@ -0,0 +1,11 @@
+"""Health-check primitives shared across Juniper services.
+
+Re-exports the model classes and probe utility so consumers can
+``from juniper_observability.health import DependencyStatus, ReadinessResponse, probe_dependency``
+without reaching into the submodules.
+"""
+
+from juniper_observability.health.models import DependencyStatus, ReadinessResponse
+from juniper_observability.health.probe import probe_dependency
+
+__all__ = ["DependencyStatus", "ReadinessResponse", "probe_dependency"]

juniper_observability-0.1.0a0/juniper_observability/health/models.py

@@ -0,0 +1,41 @@
+"""Pydantic models for ``/v1/health/ready`` responses.
+
+The R1.2 probe contract pins:
+
+* ``DependencyStatus.status`` is one of {healthy, unhealthy, degraded,
+  not_configured}.
+* ``ReadinessResponse.status`` is one of {ready, degraded, not_ready};
+  HTTP status code is 200 for ready/degraded and 503 for not_ready.
+* ``ReadinessResponse.timestamp`` is a unix-epoch float **derived from
+  timezone-aware UTC** (resolves the cascor naive-tz drift identified
+  during R1.2 implementation; matches juniper-data's BUG-JD-06 fix).
+
+These models are wire-compatible with the per-repo copies they replace.
+"""
+
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class DependencyStatus(BaseModel):
+    """Health status of a single dependency probed during readiness."""
+
+    name: str
+    status: Literal["healthy", "unhealthy", "degraded", "not_configured"]
+    latency_ms: float | None = None
+    message: str | None = None
+
+
+class ReadinessResponse(BaseModel):
+    """Standard ``/v1/health/ready`` response across all Juniper services."""
+
+    status: Literal["ready", "degraded", "not_ready"]
+    version: str
+    service: str
+    # METRICS-MON R1.2 / BUG-JD-06: timezone-aware UTC. Always epoch
+    # seconds from a tz-aware datetime — never naive.
+    timestamp: float = Field(default_factory=lambda: datetime.now(UTC).timestamp())
+    dependencies: dict[str, DependencyStatus] = Field(default_factory=dict)
+    details: dict[str, object] = Field(default_factory=dict)

juniper_observability-0.1.0a0/juniper_observability/health/probe.py

@@ -0,0 +1,49 @@
+"""Synchronous dependency-probe helper used by readiness handlers.
+
+The probe is a one-shot HTTP GET against a peer service's
+``/v1/health/live`` endpoint. ``probe_dependency`` swallows every
+exception and converts it into a ``DependencyStatus`` with status
+``unhealthy``; this is intentional — a probe failure must never bubble
+out of the readiness handler and crash the request.
+
+R4.2 will introduce an async variant that does not block the event
+loop. Until then, callers running inside async handlers should be aware
+that ``probe_dependency`` is sync and best invoked via
+``asyncio.to_thread`` if probe latency is non-trivial.
+"""
+
+import time
+import urllib.request
+
+from juniper_observability.health.models import DependencyStatus
+
+
+def probe_dependency(name: str, url: str, timeout: float = 5.0) -> DependencyStatus:
+    """Probe a dependency health endpoint. Returns status with latency.
+
+    Args:
+        name: Human-readable name of the dependency for logs/dashboards.
+        url: Health endpoint URL to probe (typically ``/v1/health/live``).
+        timeout: Connection timeout in seconds.
+
+    Returns:
+        ``DependencyStatus`` with:
+        - ``status="healthy"`` when the GET returns without raising.
+        - ``status="unhealthy"`` for any exception (connection refused,
+          timeout, non-2xx via ``HTTPError``); the exception type and
+          message are encoded into the ``message`` field.
+        - ``latency_ms`` always populated from a monotonic clock.
+    """
+    start = time.monotonic()
+    try:
+        urllib.request.urlopen(url, timeout=timeout)  # nosec B310 — internal health probe
+        latency = (time.monotonic() - start) * 1000
+        return DependencyStatus(name=name, status="healthy", latency_ms=round(latency, 1), message=url)
+    except Exception as e:  # noqa: BLE001 — probe surfaces every failure mode
+        latency = (time.monotonic() - start) * 1000
+        return DependencyStatus(
+            name=name,
+            status="unhealthy",
+            latency_ms=round(latency, 1),
+            message=f"{url} — {type(e).__name__}: {e}",
+        )

juniper_observability-0.1.0a0/juniper_observability/logging.py

@@ -0,0 +1,83 @@
+"""Structured-JSON logging primitives for Juniper services.
+
+Provides:
+
+- ``JuniperJsonFormatter`` — a ``logging.Formatter`` subclass that
+  emits one JSON object per record with stable keys (``timestamp``,
+  ``level``, ``logger``, ``message``, ``service``, ``request_id``, and
+  optional ``exception``).
+- ``configure_logging`` — installs the formatter onto the root logger
+  with the requested level, replacing any existing handlers.
+
+The ``request_id`` field is sourced from the ``request_id_var``
+ContextVar populated by ``RequestIdMiddleware`` so async handlers can
+emit log lines that correlate to the originating HTTP request without
+threading the ID through every call.
+"""
+
+import json
+import logging
+
+from juniper_observability.middleware.request_id import request_id_var
+
+# Default plain-text log format when ``log_format != "json"``. Mirrors
+# the Python convention used by every Juniper service.
+DEFAULT_LOG_FORMAT_PLAIN = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+
+# Sentinel value identifying the JSON formatter mode.
+LOG_FORMAT_JSON = "json"
+
+
+class JuniperJsonFormatter(logging.Formatter):
+    """JSON log formatter with ``request_id`` propagation.
+
+    Always emits the same set of top-level keys so log shippers can
+    parse every Juniper service's logs without per-service rules.
+    """
+
+    def __init__(self, service: str = "juniper-service") -> None:
+        super().__init__()
+        self._service = service
+
+    def format(self, record: logging.LogRecord) -> str:
+        log_entry = {
+            "timestamp": self.formatTime(record, self.datefmt),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "service": self._service,
+            "request_id": request_id_var.get(""),
+        }
+        if record.exc_info and record.exc_info[1] is not None:
+            log_entry["exception"] = self.formatException(record.exc_info)
+        return json.dumps(log_entry)
+
+
+def configure_logging(log_level: str, log_format: str, service_name: str = "juniper-service") -> None:
+    """Configure the root logger.
+
+    Args:
+        log_level: Logging level string (``"INFO"``, ``"DEBUG"``, …).
+            Unknown values fall back to ``logging.INFO``.
+        log_format: ``"json"`` for structured JSON via
+            :class:`JuniperJsonFormatter`; anything else for plain
+            text via :data:`DEFAULT_LOG_FORMAT_PLAIN`.
+        service_name: Service identity included in JSON log entries.
+    """
+    level = getattr(logging, log_level.upper(), logging.INFO)
+    root = logging.getLogger()
+    root.setLevel(level)
+
+    # Remove existing handlers to avoid duplicate output.
+    for handler in root.handlers[:]:
+        root.removeHandler(handler)
+
+    handler = logging.StreamHandler()
+    handler.setLevel(level)
+
+    if log_format == LOG_FORMAT_JSON:
+        handler.setFormatter(JuniperJsonFormatter(service=service_name))
+    else:
+        handler.setFormatter(logging.Formatter(DEFAULT_LOG_FORMAT_PLAIN))
+
+    root.addHandler(handler)

juniper_observability-0.1.0a0/juniper_observability/middleware/__init__.py

@@ -0,0 +1,6 @@
+"""Starlette middleware shared across Juniper services."""
+
+from juniper_observability.middleware.prometheus import PrometheusMiddleware
+from juniper_observability.middleware.request_id import RequestIdMiddleware, request_id_var
+
+__all__ = ["PrometheusMiddleware", "RequestIdMiddleware", "request_id_var"]

juniper_observability-0.1.0a0/juniper_observability/middleware/prometheus.py

@@ -0,0 +1,78 @@
+"""Prometheus middleware for Juniper services.
+
+METRICS-MON R1.1 / seed-01 contract:
+
+- ``endpoint`` label is set to the resolved Starlette route template
+  (e.g. ``/v1/datasets/{dataset_id}``) — never to the raw URL path.
+- Requests that do not match any registered route template collapse
+  into ``UNMATCHED_ENDPOINT_LABEL`` and increment a separate counter
+  ``<namespace>_http_unmatched_requests_total{method}``.
+- This bounds Prometheus label cardinality under attacker-controlled
+  paths or path-parameter routes; per-repo dashboards relying on the
+  unbounded raw-URL fallback have been migrated.
+
+The middleware is service-specific only by virtue of its ``namespace``
+prefix — ``juniper_data_*``, ``juniper_cascor_*``, ``juniper_canopy_*``.
+Consumers pass their identity at construction time.
+"""
+
+import time
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from juniper_observability.constants import UNMATCHED_ENDPOINT_LABEL
+
+
+class PrometheusMiddleware(BaseHTTPMiddleware):
+    """Tracks HTTP request counts and durations with bounded cardinality.
+
+    Lazily imports ``prometheus_client`` so the broader package can be
+    used without the ``[prometheus]`` extra installed.
+    """
+
+    def __init__(self, app: object, service_name: str = "juniper-service", namespace: str = "juniper") -> None:
+        super().__init__(app)
+        from prometheus_client import Counter, Histogram
+
+        prefix = f"{namespace}_" if namespace else ""
+        self._request_count = Counter(
+            f"{prefix}http_requests_total",
+            "Total HTTP requests",
+            ["method", "endpoint", "status"],
+        )
+        self._request_duration = Histogram(
+            f"{prefix}http_request_duration_seconds",
+            "HTTP request duration in seconds",
+            ["method", "endpoint"],
+        )
+        self._unmatched_count = Counter(
+            f"{prefix}http_unmatched_requests_total",
+            "HTTP requests not matching any registered route template",
+            ["method"],
+        )
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestResponseEndpoint,
+    ) -> Response:
+        start = time.perf_counter()
+        response = await call_next(request)
+        duration = time.perf_counter() - start
+
+        route = request.scope.get("route")
+        template = getattr(route, "path", None) if route is not None else None
+        method = request.method
+        if template:
+            endpoint = template
+        else:
+            endpoint = UNMATCHED_ENDPOINT_LABEL
+            self._unmatched_count.labels(method=method).inc()
+
+        status = str(response.status_code)
+        self._request_count.labels(method=method, endpoint=endpoint, status=status).inc()
+        self._request_duration.labels(method=method, endpoint=endpoint).observe(duration)
+
+        return response

juniper_observability-0.1.0a0/juniper_observability/middleware/request_id.py

@@ -0,0 +1,43 @@
+"""Request-ID propagation middleware.
+
+Injects an ``X-Request-ID`` header into every response and stores the
+value in a ContextVar so async handlers and log records can correlate
+to the originating HTTP request without threading the ID through every
+call.
+"""
+
+import uuid
+from contextvars import ContextVar
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import Response
+
+from juniper_observability.constants import HEADER_X_REQUEST_ID
+
+# Public ContextVar; ``JuniperJsonFormatter`` reads from it to embed the
+# request ID in every log record emitted during the request scope.
+request_id_var: ContextVar[str] = ContextVar("request_id", default="")
+
+
+class RequestIdMiddleware(BaseHTTPMiddleware):
+    """Injects ``X-Request-ID`` into ContextVar and response header.
+
+    If the request carries an inbound ``X-Request-ID`` header, that
+    value is propagated; otherwise a fresh UUID4 is generated. The
+    header is always echoed back on the response.
+    """
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestResponseEndpoint,
+    ) -> Response:
+        rid = request.headers.get(HEADER_X_REQUEST_ID, str(uuid.uuid4()))
+        token = request_id_var.set(rid)
+        try:
+            response = await call_next(request)
+            response.headers[HEADER_X_REQUEST_ID] = rid
+            return response
+        finally:
+            request_id_var.reset(token)

juniper_observability-0.1.0a0/juniper_observability/prometheus.py

@@ -0,0 +1,40 @@
+"""Prometheus utilities (ASGI app + build-info Info metric).
+
+These helpers wrap ``prometheus_client`` so consumers don't need to
+import the SDK directly. Both functions are lazy — ``prometheus_client``
+is only imported when the helper is called, so the package can be
+installed without the ``[prometheus]`` extra and these helpers will
+simply raise at call time.
+"""
+
+import sys
+
+
+def get_prometheus_app():
+    """Return the ASGI app for ``/metrics`` via ``make_asgi_app()``.
+
+    The returned app should typically be wrapped by a service-specific
+    auth middleware (e.g. juniper-data's SEC-16 ``MetricsAuthMiddleware``
+    IP allowlist) before being mounted.
+
+    Returns:
+        ASGI application serving Prometheus metrics in the standard
+        scrape format.
+    """
+    from prometheus_client import make_asgi_app
+
+    return make_asgi_app()
+
+
+def set_build_info(namespace: str, version: str) -> None:
+    """Register a ``<namespace>_build`` Info metric with version + python_version.
+
+    Args:
+        namespace: Metric namespace prefix (e.g. ``"juniper_data"``).
+        version: Application version string.
+    """
+    from prometheus_client import Info
+
+    python_version = f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    info = Info(f"{namespace}_build", f"Build information for {namespace.replace('_', '-')} service")
+    info.info({"version": version, "python_version": python_version})

juniper_observability-0.1.0a0/juniper_observability/sentry.py

@@ -0,0 +1,75 @@
+"""Sentry initialization with reconciled signature and SEC-10 hook.
+
+This module exposes the **superset** signature originally introduced
+in juniper-data for SEC-10 (security review of Sentry forwarding) and
+makes it the cross-service standard:
+
+- ``send_pii`` is keyword-only, defaulting to ``False``.
+- A ``before_send`` hook always scrubs ``X-API-Key``, ``Authorization``,
+  and ``Cookie`` headers from outbound events regardless of
+  ``send_default_pii`` — defense in depth so that future Sentry SDK
+  changes (replay, custom integrations) cannot leak credentials.
+
+``configure_sentry`` is a no-op when ``dsn`` is ``None`` or the empty
+string, so consumers can call it unconditionally during startup.
+"""
+
+DEFAULT_SENTRY_TRACES_SAMPLE_RATE = 0.1
+
+# SEC-10: header names that may carry API keys or session identifiers.
+_SENTRY_SENSITIVE_HEADERS = frozenset({"x-api-key", "authorization", "cookie"})
+
+
+def _strip_sensitive_headers(event, hint):  # noqa: ARG001 — Sentry hook signature
+    """Redact sensitive request headers in a Sentry event with ``[Filtered]``.
+
+    Sentry calls this via ``before_send`` for every outbound event.
+    The filter only rewrites keys in :data:`_SENTRY_SENSITIVE_HEADERS`
+    so non-sensitive diagnostic headers (user-agent, trace IDs, etc.)
+    still reach Sentry unchanged.
+    """
+    request_data = event.get("request", {}) if isinstance(event, dict) else {}
+    headers = request_data.get("headers", {}) if isinstance(request_data, dict) else {}
+    if isinstance(headers, dict):
+        for key in list(headers.keys()):
+            if key.lower() in _SENTRY_SENSITIVE_HEADERS:
+                headers[key] = "[Filtered]"
+    return event
+
+
+def configure_sentry(
+    dsn: str | None,
+    service_name: str,
+    version: str,
+    *,
+    send_pii: bool = False,
+    traces_sample_rate: float = DEFAULT_SENTRY_TRACES_SAMPLE_RATE,
+) -> None:
+    """Initialize Sentry. No-op when ``dsn`` is None or empty.
+
+    Args:
+        dsn: Sentry DSN URL. Pass ``None`` or empty string to skip
+            initialization.
+        service_name: Service name for Sentry environment tag (used in
+            the ``release`` field as ``"<service_name>@<version>"``).
+        version: Application version string.
+        send_pii: Whether to send default PII (IP addresses, etc.) to
+            Sentry. **Defaults to False** (SEC-10); operators opt in
+            explicitly via per-service env vars when they accept the
+            risk. The ``before_send`` filter still scrubs sensitive
+            headers regardless of this flag.
+        traces_sample_rate: Fraction of transactions to send (0.0–1.0).
+    """
+    if not dsn:
+        return
+
+    import sentry_sdk
+
+    sentry_sdk.init(
+        dsn=dsn,
+        send_default_pii=send_pii,
+        enable_logs=True,
+        traces_sample_rate=traces_sample_rate,
+        release=f"{service_name}@{version}",
+        before_send=_strip_sensitive_headers,
+    )