dispatch-kit 0.2.0__tar.gz → 0.3.0__tar.gz

{dispatch_kit-0.2.0 → dispatch_kit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dispatch-kit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Pure, fail-closed cost-gating for expensive remote/external work: a hard $ budget cap, backend routing (local->cloud->SDK), and opt-in audited API egress.
 Author-email: Aryan Falahatpisheh <aryanfalahat@gmail.com>
 License: MIT

{dispatch_kit-0.2.0 → dispatch_kit-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dispatch-kit"
-version = "0.2.0"
+version = "0.3.0"
 description = "Pure, fail-closed cost-gating for expensive remote/external work: a hard $ budget cap, backend routing (local->cloud->SDK), and opt-in audited API egress."
 authors = [{ name = "Aryan Falahatpisheh", email = "aryanfalahat@gmail.com" }]
 readme = "README.md"

{dispatch_kit-0.2.0 → dispatch_kit-0.3.0}/src/dispatch_kit/__init__.py

@@ -46,6 +46,7 @@ from .egress import (
 from .engine import drain
 from .estimate import CostEstimate, HostCapabilities, vram_fits
 from .faults import Contained
+from .observe import Observe, ObserveConfig
 from .provenance import Determinism, GpuContext, Provenance
 from .routing import (
     BackendCapabilities,
@@ -79,6 +80,8 @@ __all__ = [
     "Lease",
     "NoEligibleBackendError",
     "NodeIdentity",
+    "Observe",
+    "ObserveConfig",
     "Provenance",
     "RetriableError",
     "Routable",

dispatch_kit-0.3.0/src/dispatch_kit/observe.py

@@ -0,0 +1,183 @@
+"""Optional observability facade — OpenTelemetry traces + Sentry errors + structured JSON logs.
+
+Opt-in, OFF by default: nothing leaves the box unless the operator sets an env var. Construct one
+:class:`Observe` per service with a service name + an env-var prefix; until a DSN/endpoint is set,
+every call is a zero-cost no-op, so instrumentation can live permanently at the call sites. The
+export SDKs are loaded via :func:`importlib.import_module` (a runtime call, so this module — and the
+whole package — stays import-clean and dependency-free without them); the facade degrades to no-ops
+when they are absent.
+
+This owns the parts every service shares: traces, error reporting, JSON log formatting. A service
+that also exports *metrics* builds its own meter, reusing identity via :meth:`Observe.resource`.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import logging
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ObserveConfig:
+    """Per-service observability settings.
+
+    ``env_prefix`` namespaces the opt-in vars: ``<PREFIX>_SENTRY_DSN`` (falling back to the standard
+    ``SENTRY_DSN``) enables Sentry, ``<PREFIX>_LOG_JSON`` turns on JSON logs; OTLP traces follow the
+    standard ``OTEL_EXPORTER_OTLP_ENDPOINT``. ``pip_hint`` is shown when an export is requested but
+    the optional SDK extra is not installed. ``tracer_name`` names the tracer/logger.
+    """
+
+    service_name: str
+    env_prefix: str
+    pip_hint: str
+    tracer_name: str
+
+
+class _JsonFormatter(logging.Formatter):
+    """One-line JSON per record (ts/level/logger/msg + service/command) so logs are parseable
+    and shippable — searchable across containers, not just grep on one box."""
+
+    def __init__(self, service: str, command: str | None) -> None:
+        super().__init__()
+        self._base: dict[str, str] = {"service": service}
+        if command:
+            self._base["command"] = command
+
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, object] = {
+            "ts": self.formatTime(record),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+            **self._base,
+        }
+        if record.exc_info:
+            payload["exc"] = self.formatException(record.exc_info)
+        return json.dumps(payload)
+
+
+class Observe:
+    """A per-service observability facade: traces (OTel), errors (Sentry), JSON logs.
+
+    Construct with an :class:`ObserveConfig`, call :meth:`setup` once at process start, then use
+    :meth:`span` / :meth:`capture_exception` freely — both no-op when export is off. The
+    ``build_sentry`` / ``build_tracer`` methods are the seams tests patch.
+    """
+
+    def __init__(self, config: ObserveConfig) -> None:
+        self._cfg = config
+        self._log = logging.getLogger(config.tracer_name)
+        self._sentry: Any = None
+        self._tracer: Any = None
+
+    def setup(self, *, command: str | None = None) -> None:
+        """Wire whichever exporters the environment opts into. Idempotent — resets first, so it can
+        be called once per process or re-run in tests."""
+        self.reset()
+        self._init_logging(command)
+        self._init_sentry()
+        self._init_tracer(command)
+
+    def reset(self) -> None:
+        """Deactivate every exporter (before a re-:meth:`setup` and in tests)."""
+        self._sentry = None
+        self._tracer = None
+
+    def is_active(self) -> dict[str, bool]:
+        """Which exporters are live — for a health check and asserted by tests."""
+        return {"sentry": self._sentry is not None, "otel": self._tracer is not None}
+
+    @contextmanager
+    def span(self, name: str, **attributes: object) -> Iterator[Any]:
+        """Trace the wrapped block as one OTel span (with ``attributes``). A no-op context yielding
+        ``None`` when tracing is off, so call sites need no guard."""
+        tracer = self._tracer
+        if tracer is None:
+            yield None
+            return
+        with tracer.start_as_current_span(name) as active:
+            for key, value in attributes.items():
+                active.set_attribute(key, value)
+            yield active
+
+    def capture_exception(self, exc: BaseException, **tags: object) -> None:
+        """Report a caught exception to Sentry with ``tags`` for grouping. No-op when off — the
+        caller still records its own failure normally."""
+        sentry = self._sentry
+        if sentry is None:
+            return
+        with sentry.new_scope() as scope:
+            for key, value in tags.items():
+                scope.set_tag(key, str(value))
+            sentry.capture_exception(exc)
+
+    def otlp_endpoint(self) -> str | None:
+        """The OTLP endpoint if set — a service building its own meter checks this."""
+        return os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT") or None
+
+    def resource(self, **extra: Any) -> Any:
+        """An OTel ``Resource`` carrying ``service.name`` + ``extra`` — so a service's own meter
+        shares this service's identity. Requires the opentelemetry SDK."""
+        resources = importlib.import_module("opentelemetry.sdk.resources")
+        return resources.Resource.create({"service.name": self._cfg.service_name, **extra})
+
+    def _init_logging(self, command: str | None) -> None:
+        if not os.environ.get(f"{self._cfg.env_prefix}_LOG_JSON"):
+            return
+        fmt = _JsonFormatter(self._cfg.service_name, command)
+        root = logging.getLogger()
+        if not root.handlers:
+            root.addHandler(logging.StreamHandler())
+        for handler in root.handlers:
+            handler.setFormatter(fmt)
+
+    def _init_sentry(self) -> None:
+        dsn = os.environ.get(f"{self._cfg.env_prefix}_SENTRY_DSN") or os.environ.get("SENTRY_DSN")
+        if not dsn:
+            return
+        try:
+            self._sentry = self.build_sentry(dsn)
+        except ImportError:
+            self._log.warning("SENTRY_DSN set but sentry-sdk is missing — %s", self._cfg.pip_hint)
+            return
+        self._log.info("Sentry error reporting enabled")
+
+    def _init_tracer(self, command: str | None) -> None:
+        endpoint = self.otlp_endpoint()
+        if not endpoint:
+            return
+        try:
+            self._tracer = self.build_tracer(command)
+        except ImportError:
+            self._log.warning(
+                "OTEL_EXPORTER_OTLP_ENDPOINT set but opentelemetry is missing — %s",
+                self._cfg.pip_hint,
+            )
+            return
+        self._log.info("OpenTelemetry export enabled -> %s", endpoint)
+
+    def build_sentry(self, dsn: str) -> Any:
+        """Initialise the real Sentry SDK (errors only; OTel owns traces). The dynamic import is the
+        seam tests patch + the ImportError surface when the extra is absent."""
+        sentry_sdk = importlib.import_module("sentry_sdk")
+        sentry_sdk.init(dsn=dsn, send_default_pii=False, traces_sample_rate=0.0)
+        return sentry_sdk
+
+    def build_tracer(self, command: str | None) -> Any:
+        """Register an OTLP-exporting tracer provider over this service's resource; return its
+        tracer. Endpoint/headers are read from the standard ``OTEL_EXPORTER_OTLP_*`` env."""
+        trace = importlib.import_module("opentelemetry.trace")
+        otlp = importlib.import_module("opentelemetry.exporter.otlp.proto.http.trace_exporter")
+        sdk_trace = importlib.import_module("opentelemetry.sdk.trace")
+        sdk_export = importlib.import_module("opentelemetry.sdk.trace.export")
+        extra = {f"{self._cfg.tracer_name}.command": command} if command else {}
+        provider = sdk_trace.TracerProvider(resource=self.resource(**extra))
+        provider.add_span_processor(sdk_export.BatchSpanProcessor(otlp.OTLPSpanExporter()))
+        trace.set_tracer_provider(provider)
+        return trace.get_tracer(self._cfg.tracer_name)

{dispatch_kit-0.2.0 → dispatch_kit-0.3.0}/src/dispatch_kit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dispatch-kit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Pure, fail-closed cost-gating for expensive remote/external work: a hard $ budget cap, backend routing (local->cloud->SDK), and opt-in audited API egress.
 Author-email: Aryan Falahatpisheh <aryanfalahat@gmail.com>
 License: MIT

{dispatch_kit-0.2.0 → dispatch_kit-0.3.0}/src/dispatch_kit.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ src/dispatch_kit/egress.py
 src/dispatch_kit/engine.py
 src/dispatch_kit/estimate.py
 src/dispatch_kit/faults.py
+src/dispatch_kit/observe.py
 src/dispatch_kit/provenance.py
 src/dispatch_kit/py.typed
 src/dispatch_kit/routing.py
@@ -24,5 +25,6 @@ tests/test_egress.py
 tests/test_engine.py
 tests/test_estimate.py
 tests/test_faults.py
+tests/test_observe.py
 tests/test_provenance.py
 tests/test_routing.py

dispatch_kit-0.3.0/tests/test_observe.py

@@ -0,0 +1,151 @@
+"""The observability facade is OFF by default and a safe no-op until an env var opts in.
+
+The real SDKs are patched via the ``build_sentry`` / ``build_tracer`` seams, so these tests need
+neither the export extras nor a network endpoint.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+import pytest
+
+from dispatch_kit.observe import Observe, ObserveConfig, _JsonFormatter
+
+_CFG = ObserveConfig(
+    service_name="svc",
+    env_prefix="SVC",
+    pip_hint="pip install 'svc[observe]'",
+    tracer_name="svc",
+)
+
+
+@pytest.fixture
+def obs(monkeypatch: pytest.MonkeyPatch) -> Observe:
+    """A fresh facade with every opt-in env var cleared."""
+    for var in ("SVC_SENTRY_DSN", "SENTRY_DSN", "OTEL_EXPORTER_OTLP_ENDPOINT", "SVC_LOG_JSON"):
+        monkeypatch.delenv(var, raising=False)
+    return Observe(_CFG)
+
+
+class _FakeScope:
+    def __init__(self) -> None:
+        self.tags: dict[str, str] = {}
+
+    def __enter__(self) -> _FakeScope:
+        return self
+
+    def __exit__(self, *_exc: object) -> bool:
+        return False
+
+    def set_tag(self, key: str, value: str) -> None:
+        self.tags[key] = value
+
+
+class _FakeSentry:
+    def __init__(self) -> None:
+        self.captured: list[tuple[BaseException, dict[str, str]]] = []
+        self._scope = _FakeScope()
+
+    def new_scope(self) -> _FakeScope:
+        self._scope = _FakeScope()
+        return self._scope
+
+    def capture_exception(self, exc: BaseException) -> None:
+        self.captured.append((exc, dict(self._scope.tags)))
+
+
+class _FakeSpan:
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.attrs: dict[str, object] = {}
+
+    def __enter__(self) -> _FakeSpan:
+        return self
+
+    def __exit__(self, *_exc: object) -> bool:
+        return False
+
+    def set_attribute(self, key: str, value: object) -> None:
+        self.attrs[key] = value
+
+
+class _FakeTracer:
+    def __init__(self) -> None:
+        self.spans: list[_FakeSpan] = []
+
+    def start_as_current_span(self, name: str) -> _FakeSpan:
+        span = _FakeSpan(name)
+        self.spans.append(span)
+        return span
+
+
+def test_inactive_by_default_is_a_safe_noop(obs: Observe) -> None:
+    obs.setup()
+    assert obs.is_active() == {"sentry": False, "otel": False}
+    with obs.span("op", tag="t") as active:
+        assert active is None
+    obs.capture_exception(ValueError("x"), op="t")  # must not raise
+
+
+def test_sentry_opt_in_forwards_exception_with_tags(
+    obs: Observe, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    fake = _FakeSentry()
+    monkeypatch.setenv("SVC_SENTRY_DSN", "https://k@example.test/1")
+    monkeypatch.setattr(obs, "build_sentry", lambda _dsn: fake)
+    obs.setup()
+    assert obs.is_active()["sentry"] is True
+    err = ValueError("boom")
+    obs.capture_exception(err, op="x", id="r1")
+    assert fake.captured == [(err, {"op": "x", "id": "r1"})]
+
+
+def test_otel_opt_in_records_spans(obs: Observe, monkeypatch: pytest.MonkeyPatch) -> None:
+    tracer = _FakeTracer()
+    monkeypatch.setenv("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4318")
+    monkeypatch.setattr(obs, "build_tracer", lambda _cmd: tracer)
+    obs.setup(command="work")
+    assert obs.is_active()["otel"] is True
+    with obs.span("job", op="x") as active:
+        assert active is not None
+    assert tracer.spans[0].name == "job"
+    assert tracer.spans[0].attrs == {"op": "x"}
+
+
+def test_missing_extra_logs_and_degrades(
+    obs: Observe, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
+) -> None:
+    def _no_sdk(_dsn: str) -> object:
+        raise ImportError("no sentry_sdk")
+
+    monkeypatch.setenv("SVC_SENTRY_DSN", "https://k@example.test/1")
+    monkeypatch.setattr(obs, "build_sentry", _no_sdk)
+    with caplog.at_level(logging.WARNING):
+        obs.setup()
+    assert obs.is_active()["sentry"] is False
+    assert any("sentry-sdk" in rec.message for rec in caplog.records)
+
+
+def test_setup_is_idempotent_and_resets(obs: Observe, monkeypatch: pytest.MonkeyPatch) -> None:
+    fake = _FakeSentry()
+    monkeypatch.setenv("SVC_SENTRY_DSN", "https://k@example.test/1")
+    monkeypatch.setattr(obs, "build_sentry", lambda _dsn: fake)
+    obs.setup()
+    assert obs.is_active()["sentry"] is True
+    monkeypatch.delenv("SVC_SENTRY_DSN")
+    obs.setup()
+    assert obs.is_active()["sentry"] is False
+
+
+def test_json_formatter_emits_structured_record() -> None:
+    formatter = _JsonFormatter("svc", "work")
+    record = logging.LogRecord("svc.x", logging.INFO, "f.py", 1, "hello %s", ("world",), None)
+    payload = json.loads(formatter.format(record))
+    assert payload["service"] == "svc"
+    assert payload["command"] == "work"
+    assert payload["level"] == "INFO"
+    assert payload["logger"] == "svc.x"
+    assert payload["msg"] == "hello world"
+    assert "ts" in payload