xyberos-observability 0.1.0__tar.gz

xyberos_observability-0.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: xyberos-observability
+Version: 0.1.0
+Summary: Observability exporters plugin (RFC-0019, M10): OTel, Prometheus, Langfuse, Sentry as thin EventBus exporters
+License: Apache-2.0
+Keywords: xyberos,plugin,observability,opentelemetry,prometheus,langfuse,sentry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk; extra == "otel"
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client; extra == "prometheus"
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk; extra == "sentry"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# xyberos-observability (M10)
+
+Observability/telemetry exporters for Xyberos. Turns the runtime's event stream
+into traces and metrics for **OpenTelemetry**, **Prometheus**, **Langfuse**, and
+**Sentry** — satisfying RFC-0019 Track L, milestone M10.
+
+## Install
+
+```bash
+pip install -e ./observability
+```
+
+Optional extras:
+
+```bash
+pip install -e "./observability[otel]"      # opentelemetry-sdk (in-memory spans by default)
+pip install -e "./observability[prometheus]"# prometheus-client
+pip install -e "./observability[sentry]"    # sentry-sdk
+```
+
+## How it works
+
+Xyberos emits events (`runtime.request_started`, `brain.response_produced`,
+`memory.stored`, ...) on its `EventBus`. This plugin attaches an
+`EventRecorder` that forwards each event to the configured exporters:
+
+| Exporter | Destination | What it does |
+| --- | --- | --- |
+| `OpenTelemetryExporter` | OTel span pipeline | One span per event, named `event.name`, with `event.*` attributes (plus `event.prompt`). Defaults to an `InMemorySpanExporter` so traces are inspectable without a collector. |
+| `PrometheusExporter` | Prometheus registry | `xyberos_events_total{event="..."}` counter, one per event name. |
+| `LangfuseExporter` | Langfuse `/api/public/ingestion` | One `observation-create` item per event with `name`, `input` (prompt) and `output` (event data). Basic auth with `public_key:secret_key`. |
+| `SentryExporter` | Sentry SDK | Adds a breadcrumb per event; captures a message for failures (`runtime.request_failed`, `brain.error`). |
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_observability import ObservabilityPlugin, OpenTelemetryExporter
+
+app = create_app()
+app.load_plugin(ObservabilityPlugin(exporters=[OpenTelemetryExporter()]))
+
+reply = app.chat("hello")          # emits events -> spans
+```
+
+Select exporters by environment variable (comma-separated) instead:
+
+```bash
+export OBSERVABILITY_EXPORTERS=otel,prometheus,langfuse,sentry
+```
+
+```python
+from xyberos_observability import ObservabilityPlugin
+
+app.load_plugin(ObservabilityPlugin())
+```
+
+For Langfuse, set `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` and
+`LANGFUSE_HOST` (defaults `https://cloud.langfuse.com`).
+
+## Example
+
+```bash
+python examples/trace_a_chat.py                       # inspect in-memory spans
+python examples/trace_a_chat.py --prometheus          # also track a counter
+python examples/trace_a_chat.py --langfuse            # POST traces to Langfuse
+```
+
+## Tests
+
+```bash
+python -m pytest observability/tests -q
+```
+
+Tests use injectable transports / in-memory exporters, so nothing touches the
+network or a real collector. The DoD test (`tests/test_plugin.py`) runs
+`app.chat(...)` and asserts a trace lands in OTel and Langfuse.

xyberos_observability-0.1.0/README.md

@@ -0,0 +1,77 @@
+# xyberos-observability (M10)
+
+Observability/telemetry exporters for Xyberos. Turns the runtime's event stream
+into traces and metrics for **OpenTelemetry**, **Prometheus**, **Langfuse**, and
+**Sentry** — satisfying RFC-0019 Track L, milestone M10.
+
+## Install
+
+```bash
+pip install -e ./observability
+```
+
+Optional extras:
+
+```bash
+pip install -e "./observability[otel]"      # opentelemetry-sdk (in-memory spans by default)
+pip install -e "./observability[prometheus]"# prometheus-client
+pip install -e "./observability[sentry]"    # sentry-sdk
+```
+
+## How it works
+
+Xyberos emits events (`runtime.request_started`, `brain.response_produced`,
+`memory.stored`, ...) on its `EventBus`. This plugin attaches an
+`EventRecorder` that forwards each event to the configured exporters:
+
+| Exporter | Destination | What it does |
+| --- | --- | --- |
+| `OpenTelemetryExporter` | OTel span pipeline | One span per event, named `event.name`, with `event.*` attributes (plus `event.prompt`). Defaults to an `InMemorySpanExporter` so traces are inspectable without a collector. |
+| `PrometheusExporter` | Prometheus registry | `xyberos_events_total{event="..."}` counter, one per event name. |
+| `LangfuseExporter` | Langfuse `/api/public/ingestion` | One `observation-create` item per event with `name`, `input` (prompt) and `output` (event data). Basic auth with `public_key:secret_key`. |
+| `SentryExporter` | Sentry SDK | Adds a breadcrumb per event; captures a message for failures (`runtime.request_failed`, `brain.error`). |
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_observability import ObservabilityPlugin, OpenTelemetryExporter
+
+app = create_app()
+app.load_plugin(ObservabilityPlugin(exporters=[OpenTelemetryExporter()]))
+
+reply = app.chat("hello")          # emits events -> spans
+```
+
+Select exporters by environment variable (comma-separated) instead:
+
+```bash
+export OBSERVABILITY_EXPORTERS=otel,prometheus,langfuse,sentry
+```
+
+```python
+from xyberos_observability import ObservabilityPlugin
+
+app.load_plugin(ObservabilityPlugin())
+```
+
+For Langfuse, set `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` and
+`LANGFUSE_HOST` (defaults `https://cloud.langfuse.com`).
+
+## Example
+
+```bash
+python examples/trace_a_chat.py                       # inspect in-memory spans
+python examples/trace_a_chat.py --prometheus          # also track a counter
+python examples/trace_a_chat.py --langfuse            # POST traces to Langfuse
+```
+
+## Tests
+
+```bash
+python -m pytest observability/tests -q
+```
+
+Tests use injectable transports / in-memory exporters, so nothing touches the
+network or a real collector. The DoD test (`tests/test_plugin.py`) runs
+`app.chat(...)` and asserts a trace lands in OTel and Langfuse.

xyberos_observability-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "xyberos-observability"
+version = "0.1.0"
+description = "Observability exporters plugin (RFC-0019, M10): OTel, Prometheus, Langfuse, Sentry as thin EventBus exporters"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "Apache-2.0"}
+dependencies = ["xyberos>=1.0"]
+keywords = ["xyberos", "plugin", "observability", "opentelemetry", "prometheus", "langfuse", "sentry"]
+
+[project.optional-dependencies]
+otel = ["opentelemetry-sdk"]
+prometheus = ["prometheus-client"]
+sentry = ["sentry-sdk"]
+test = ["pytest"]
+
+[project.entry-points."xyberos.plugins"]
+observability = "xyberos_observability.plugin:plugin"
+
+[tool.setuptools]
+packages = ["xyberos_observability"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

xyberos_observability-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

xyberos_observability-0.1.0/tests/test_langfuse.py

@@ -0,0 +1,41 @@
+"""Tests for the Langfuse exporter (injectable transport, no network)."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from xyberos.events import Event
+from xyberos.exceptions.provider import ProviderError
+
+from xyberos_observability import LangfuseExporter
+
+
+def _fake_request(seen: dict):
+    def request(method, url, **kwargs):
+        seen.update({"url": url, "headers": kwargs["headers"], "payload": kwargs["json_body"]})
+        return 200, {"success": True}
+
+    return request
+
+
+def test_export_sends_batch_item():
+    seen: dict = {}
+    exporter = LangfuseExporter("pk", "sk", host="https://langfuse.example", request=_fake_request(seen))
+    exporter.export(
+        Event(name="brain.response_produced", context=SimpleNamespace(prompt="hi"), data={"response": "hello"})
+    )
+
+    assert exporter.count == 1
+    assert seen["url"] == "https://langfuse.example/api/public/ingestion"
+    assert seen["headers"]["Authorization"].startswith("Basic ")
+    batch = seen["payload"]["batch"]
+    assert batch[0]["name"] == "brain.response_produced"
+    assert batch[0]["input"] == "hi"
+    assert batch[0]["output"] == {"response": "hello"}
+
+
+def test_requires_keys():
+    exporter = LangfuseExporter(public_key=None, secret_key=None, request=lambda *a, **k: (200, {}))
+    with pytest.raises(ProviderError, match="LANGFUSE_PUBLIC_KEY"):
+        exporter.export(Event(name="kernel.started"))

xyberos_observability-0.1.0/tests/test_otel.py

@@ -0,0 +1,33 @@
+"""Tests for the OpenTelemetry exporter (in-memory spans, no collector)."""
+
+from __future__ import annotations
+
+import importlib.util
+from types import SimpleNamespace
+
+import pytest
+from xyberos.events import Event
+
+from xyberos_observability import OpenTelemetryExporter
+
+pytestmark = pytest.mark.skipif(
+    importlib.util.find_spec("opentelemetry") is None,
+    reason="opentelemetry-sdk is not installed",
+)
+
+
+def test_events_become_spans():
+    exporter = OpenTelemetryExporter()
+    exporter.export(Event(name="runtime.request_started", context=SimpleNamespace(prompt="hi"), data={"x": 1}))
+    exporter.export(Event(name="brain.response_produced", data={"response": "hello"}))
+
+    spans = exporter.spans()
+    assert [span.name for span in spans] == ["runtime.request_started", "brain.response_produced"]
+    assert spans[0].attributes["event.prompt"] == "hi"
+    assert spans[1].attributes["event.response"] == "hello"
+
+
+def test_exporter_is_callable():
+    exporter = OpenTelemetryExporter()
+    exporter(Event(name="kernel.started"))
+    assert [span.name for span in exporter.spans()] == ["kernel.started"]

xyberos_observability-0.1.0/tests/test_plugin.py

@@ -0,0 +1,62 @@
+"""M10 DoD: a trace lands in OTel / Langfuse from ``app.chat(...)``."""
+
+from __future__ import annotations
+
+import importlib.util
+
+import pytest
+from xyberos import create_app
+
+from xyberos_observability import LangfuseExporter, ObservabilityPlugin, OpenTelemetryExporter
+
+
+def test_plugin_conforms_to_contract():
+    plugin = ObservabilityPlugin()
+    assert plugin.name == "observability"
+    assert callable(plugin.register) and callable(plugin.unregister)
+
+
+def test_unconfigured_register_is_safe():
+    app = create_app()
+    app.load_plugin(ObservabilityPlugin())  # no exporters -> no-op
+    assert app.plugins.names == ("observability",)
+    app.unload_plugin("observability")
+
+
+@pytest.mark.skipif(importlib.util.find_spec("opentelemetry") is None, reason="opentelemetry-sdk not installed")
+def test_trace_lands_in_otel_from_chat():
+    otel = OpenTelemetryExporter()
+    app = create_app()
+    app.load_plugin(ObservabilityPlugin(exporters=[otel]))
+
+    app.chat("hello")  # the DoD: a trace lands in OTel from app.chat(...)
+
+    app.unload_plugin("observability")
+    names = [span.name for span in otel.spans()]
+    assert any("request" in name for name in names)
+    assert any("response" in name for name in names)
+
+
+def test_trace_lands_in_langfuse_from_chat():
+    sent: list[dict] = []
+
+    def request(method, url, **kwargs):
+        sent.append(kwargs["json_body"])
+        return 200, {}
+
+    langfuse = LangfuseExporter("pk", "sk", host="https://langfuse.example", request=request)
+    app = create_app()
+    app.load_plugin(ObservabilityPlugin(exporters=[langfuse]))
+
+    app.chat("hello")
+
+    app.unload_plugin("observability")
+    assert sent, "expected at least one ingestion payload"
+    names = {item["batch"][0]["name"] for item in sent}
+    assert "brain.response_produced" in names
+
+
+def test_unknown_exporter_raises(monkeypatch):
+    monkeypatch.setenv("OBSERVABILITY_EXPORTERS", "bogus")
+    with pytest.raises(ValueError, match="unknown exporter"):
+        ObservabilityPlugin().exporters()

xyberos_observability-0.1.0/tests/test_prometheus.py

@@ -0,0 +1,37 @@
+"""Tests for the Prometheus exporter (isolated registry)."""
+
+from __future__ import annotations
+
+import importlib.util
+
+import pytest
+from xyberos.events import Event
+
+from xyberos_observability import PrometheusExporter
+
+pytestmark = pytest.mark.skipif(
+    importlib.util.find_spec("prometheus_client") is None,
+    reason="prometheus-client is not installed",
+)
+
+
+def test_counter_increments_per_event_name():
+    from prometheus_client import CollectorRegistry
+
+    registry = CollectorRegistry()
+    exporter = PrometheusExporter(registry=registry)
+    exporter.export(Event(name="brain.response_produced"))
+    exporter.export(Event(name="brain.response_produced"))
+    exporter.export(Event(name="memory.stored"))
+
+    assert exporter.value("brain.response_produced") == 2.0
+    assert exporter.value("memory.stored") == 1.0
+    assert exporter.value("never.emitted") == 0.0
+
+
+def test_value_without_injected_registry():
+    # default (global) registry — value() must still reflect counts
+    exporter = PrometheusExporter()
+    exporter.export(Event(name="kernel.started"))
+    exporter.export(Event(name="kernel.started"))
+    assert exporter.value("kernel.started") == 2.0

xyberos_observability-0.1.0/tests/test_sentry.py

@@ -0,0 +1,23 @@
+"""Tests for the Sentry exporter (injected capture/breadcrumb functions)."""
+
+from __future__ import annotations
+
+from xyberos.events import Event
+
+from xyberos_observability import SentryExporter
+
+
+def test_breadcrumb_and_capture():
+    breadcrumbs: list[dict] = []
+    captures: list[str] = []
+
+    exporter = SentryExporter(
+        add_breadcrumb=lambda b: breadcrumbs.append(b),
+        capture_message=lambda m: captures.append(m),
+    )
+    exporter.export(Event(name="brain.response_produced", data={"response": "hello"}))
+    exporter.export(Event(name="runtime.request_failed", data={"error": "boom"}))
+
+    assert breadcrumbs[0]["message"] == "brain.response_produced"
+    assert breadcrumbs[0]["data"] == {"response": "hello"}
+    assert captures[0].startswith("Xyberos runtime.request_failed")

xyberos_observability-0.1.0/xyberos_observability/__init__.py

@@ -0,0 +1,20 @@
+"""Observability exporters plugin (RFC-0019, M10).
+
+Thin :class:`~xyberos.events.Exporter` callables that plug into the core
+``EventBus`` through an ``EventRecorder`` — the observability hub stays inside
+Xyberos. Provides OpenTelemetry, Prometheus, Langfuse and Sentry exporters.
+"""
+
+from .langfuse import LangfuseExporter
+from .otel import OpenTelemetryExporter
+from .plugin import ObservabilityPlugin
+from .prometheus import PrometheusExporter
+from .sentry import SentryExporter
+
+__all__ = [
+    "LangfuseExporter",
+    "ObservabilityPlugin",
+    "OpenTelemetryExporter",
+    "PrometheusExporter",
+    "SentryExporter",
+]

xyberos_observability-0.1.0/xyberos_observability/http.py

@@ -0,0 +1,60 @@
+"""A tiny stdlib HTTP helper (no third-party deps).
+
+``default_request`` performs one HTTP request with ``urllib`` and returns
+``(status, body)`` where ``body`` is parsed JSON when the response is JSON,
+otherwise raw text. Injectable so tests run without a network.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable
+
+#: (method, url, *, json_body, raw_body, headers, query, timeout) -> (status, body)
+RequestTransport = Callable[..., tuple[int, Any]]
+
+
+def default_request(
+    method: str,
+    url: str,
+    *,
+    json_body: Any = None,
+    raw_body: bytes | None = None,
+    headers: dict[str, str] | None = None,
+    query: dict[str, Any] | None = None,
+    timeout: float = 30.0,
+) -> tuple[int, Any]:
+    """Send one request and return ``(status, parsed_json_or_text)``."""
+    final_url = url
+    if query:
+        separator = "&" if "?" in url else "?"
+        final_url = url + separator + urllib.parse.urlencode(query)
+
+    data: bytes | None = None
+    request_headers = dict(headers or {})
+    if raw_body is not None:
+        data = raw_body
+    elif json_body is not None:
+        data = json.dumps(json_body).encode("utf-8")
+        request_headers.setdefault("Content-Type", "application/json")
+
+    request = urllib.request.Request(
+        final_url, data=data, headers=request_headers, method=method
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            raw = response.read()
+            content_type = response.headers.get("Content-Type", "")
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.read().decode("utf-8", errors="replace")
+
+    text = raw.decode("utf-8", errors="replace")
+    if "application/json" in content_type or text.lstrip().startswith("{"):
+        try:
+            return 200, json.loads(text)
+        except json.JSONDecodeError:
+            return 200, text
+    return 200, text

xyberos_observability-0.1.0/xyberos_observability/langfuse.py

@@ -0,0 +1,76 @@
+"""Langfuse exporter — pushes events to the Langfuse ingestion API (stdlib HTTP).
+
+Each event becomes one ``observation-create`` batch item. The transport is
+injectable so tests run without a network; the exporter also records what it
+has sent for inspection.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import time
+import uuid
+from typing import Any
+
+from xyberos.events import Event
+from xyberos.exceptions.provider import ProviderError
+
+from .http import RequestTransport, default_request
+
+
+class LangfuseExporter:
+    """Sends each Xyberos event to Langfuse's ``/api/public/ingestion``."""
+
+    def __init__(
+        self,
+        public_key: str | None = None,
+        secret_key: str | None = None,
+        *,
+        host: str | None = None,
+        request: RequestTransport | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        self._public_key = public_key if public_key is not None else os.getenv("LANGFUSE_PUBLIC_KEY")
+        self._secret_key = secret_key if secret_key is not None else os.getenv("LANGFUSE_SECRET_KEY")
+        self._host = (host or os.getenv("LANGFUSE_HOST") or "https://cloud.langfuse.com").rstrip("/")
+        self._request = request or default_request
+        self._timeout = timeout
+        self.sent: list[dict[str, Any]] = []
+        self._last_status: int | None = None
+
+    @property
+    def count(self) -> int:
+        return len(self.sent)
+
+    def export(self, event: Event) -> None:
+        if not (self._public_key and self._secret_key):
+            raise ProviderError(
+                "Langfuse requires LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY"
+            )
+        prompt = getattr(event.context, "prompt", None)
+        payload: dict[str, Any] = {
+            "batch": [
+                {
+                    "id": uuid.uuid4().hex,
+                    "type": "observation-create",
+                    "timestamp": time.time() * 1000,
+                    "name": event.name,
+                    "input": str(prompt) if prompt else None,
+                    "output": dict(event.data or {}),
+                }
+            ]
+        }
+        credentials = base64.b64encode(f"{self._public_key}:{self._secret_key}".encode()).decode("ascii")
+        status, _body = self._request(
+            "POST",
+            f"{self._host}/api/public/ingestion",
+            json_body=payload,
+            headers={"Authorization": f"Basic {credentials}"},
+            timeout=self._timeout,
+        )
+        self._last_status = status
+        self.sent.append(payload)
+
+    def __call__(self, event: Event) -> None:
+        self.export(event)

xyberos_observability-0.1.0/xyberos_observability/otel.py

@@ -0,0 +1,75 @@
+"""OpenTelemetry exporter — one span per Xyberos event (lazy SDK).
+
+Builds a default SDK ``TracerProvider`` with a ``SimpleSpanProcessor`` on an
+``InMemorySpanExporter`` so traces are inspectable in tests; a ``tracer`` (or a
+``span_exporter``) can be injected. Import ``opentelemetry-sdk`` lazily.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from xyberos.events import Event
+from xyberos.exceptions.provider import ProviderError
+
+
+class OpenTelemetryExporter:
+    """Turns each :class:`~xyberos.events.Event` into an OTel span."""
+
+    def __init__(self, *, tracer: Any | None = None, span_exporter: Any | None = None) -> None:
+        self._tracer = tracer
+        self._span_exporter = span_exporter
+
+    def export(self, event: Event) -> None:
+        tracer = self._get_tracer()
+        with tracer.start_as_current_span(event.name) as span:
+            span.set_attribute("event.name", event.name)
+            for key, value in (event.data or {}).items():
+                span.set_attribute(f"event.{key}", str(value))
+            prompt = getattr(event.context, "prompt", None)
+            if prompt:
+                span.set_attribute("event.prompt", str(prompt))
+
+    def __call__(self, event: Event) -> None:
+        self.export(event)
+
+    def spans(self) -> list[Any]:
+        """Return finished spans from the injected/exposed span exporter."""
+        exporter = self._get_span_exporter()
+        return list(exporter.get_finished_spans()) if exporter is not None else []
+
+    # -- internals ----------------------------------------------------------
+
+    def _get_tracer(self) -> Any:
+        if self._tracer is not None:
+            return self._tracer
+        try:
+            opentelemetry_trace = importlib.import_module("opentelemetry.trace")
+            otel_sdk = importlib.import_module("opentelemetry.sdk.trace")
+        except ImportError as exc:
+            raise ProviderError(
+                "OpenTelemetry requires 'opentelemetry-sdk'; install with "
+                "'pip install xyberos-observability[otel]'"
+            ) from exc
+        provider = otel_sdk.TracerProvider()
+        provider.add_span_processor(self._span_processor(self._get_span_exporter()))
+        self._tracer = opentelemetry_trace.get_tracer("xyberos", tracer_provider=provider)
+        return self._tracer
+
+    def _get_span_exporter(self) -> Any:
+        if self._span_exporter is not None:
+            return self._span_exporter
+        try:
+            in_memory = importlib.import_module(
+                "opentelemetry.sdk.trace.export.in_memory_span_exporter"
+            )
+        except ImportError as exc:  # pragma: no cover - guarded by _get_tracer
+            raise ProviderError("OpenTelemetry SDK is not installed") from exc
+        self._span_exporter = in_memory.InMemorySpanExporter()
+        return self._span_exporter
+
+    @staticmethod
+    def _span_processor(exporter: Any) -> Any:
+        export_module = importlib.import_module("opentelemetry.sdk.trace.export")
+        return export_module.SimpleSpanProcessor(exporter)

xyberos_observability-0.1.0/xyberos_observability/plugin.py

@@ -0,0 +1,91 @@
+"""Observability plugin entry point (RFC-0019, M10).
+
+Wires an :class:`~xyberos.events.EventRecorder` (with the configured exporters)
+into the app's ``EventBus``. Exporters are selected by name
+(``OBSERVABILITY_EXPORTERS`` = comma-separated ``otel``, ``prometheus``,
+``langfuse``, ``sentry``) or passed explicitly. With none configured the
+plugin registers nothing (logs a warning).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from xyberos.contracts import Plugin
+from xyberos.events import EventRecorder, Exporter
+
+from .langfuse import LangfuseExporter
+from .otel import OpenTelemetryExporter
+from .prometheus import PrometheusExporter
+from .sentry import SentryExporter
+
+EXPORTER_BUILDERS: dict[str, Any] = {
+    "otel": lambda: OpenTelemetryExporter(),
+    "prometheus": lambda: PrometheusExporter(),
+    "langfuse": lambda: LangfuseExporter(),
+    "sentry": lambda: SentryExporter(),
+}
+
+
+class ObservabilityPlugin(Plugin):
+    """Subscribes an ``EventRecorder`` with the configured exporters."""
+
+    def __init__(
+        self,
+        exporters: list[Exporter] | None = None,
+        *,
+        env_prefix: str = "OBSERVABILITY",
+    ) -> None:
+        self._exporters_arg = exporters
+        self._env_prefix = env_prefix
+        self._recorder: EventRecorder | None = None
+
+    @property
+    def name(self) -> str:
+        return "observability"
+
+    def exporters(self) -> list[Exporter]:
+        if self._exporters_arg is not None:
+            return list(self._exporters_arg)
+        names = [
+            name.strip().lower()
+            for name in os.getenv(f"{self._env_prefix}_EXPORTERS", "").split(",")
+            if name.strip()
+        ]
+        built: list[Exporter] = []
+        for name in names:
+            if name not in EXPORTER_BUILDERS:
+                raise ValueError(
+                    f"unknown exporter '{name}' (choose from {sorted(EXPORTER_BUILDERS)})"
+                )
+            built.append(EXPORTER_BUILDERS[name]())
+        return built
+
+    def register(self, kernel: object) -> None:
+        try:
+            exporters = self.exporters()
+        except ValueError as exc:
+            logger = getattr(kernel, "logger", None)
+            if logger is not None and callable(getattr(logger, "warning", None)):
+                logger.warning("observability plugin not configured: %s", exc)
+            return
+        if not exporters:
+            logger = getattr(kernel, "logger", None)
+            if logger is not None and callable(getattr(logger, "warning", None)):
+                logger.warning(
+                    "observability plugin not configured: set %s_EXPORTERS", self._env_prefix
+                )
+            return
+        events = kernel.resolve("events")
+        self._recorder = EventRecorder(exporters=exporters).subscribe_to(events)
+        kernel.register("observability", self._recorder, replace=True)
+
+    def unregister(self, kernel: object) -> None:
+        if self._recorder is not None:
+            self._recorder.unsubscribe_from(kernel.resolve("events"))
+            self._recorder = None
+
+
+#: Auto-discovered by ``app.load_entry_points()``.
+plugin = ObservabilityPlugin()

xyberos_observability-0.1.0/xyberos_observability/prometheus.py

@@ -0,0 +1,52 @@
+"""Prometheus exporter — counts Xyberos events per name (lazy ``prometheus_client``)."""
+
+from __future__ import annotations
+
+import importlib
+from collections import defaultdict
+from typing import Any
+
+from xyberos.events import Event
+from xyberos.exceptions.provider import ProviderError
+
+
+class PrometheusExporter:
+    """Increments a ``xyberos_events_total`` counter labeled by event name."""
+
+    METRIC_NAME = "xyberos_events_total"
+
+    def __init__(self, *, registry: Any | None = None) -> None:
+        self._registry = registry
+        self._counter: Any = None
+        self._counts: dict[str, int] = defaultdict(int)
+
+    def export(self, event: Event) -> None:
+        self._counts[event.name] += 1
+        self._get_counter().labels(event=event.name).inc()
+
+    def __call__(self, event: Event) -> None:
+        self.export(event)
+
+    def value(self, event_name: str) -> float:
+        """The current count for ``event_name`` (0.0 when never emitted)."""
+        return float(self._counts.get(event_name, 0.0))
+
+    # -- internals ----------------------------------------------------------
+
+    def _get_counter(self) -> Any:
+        if self._counter is not None:
+            return self._counter
+        try:
+            prometheus_client = importlib.import_module("prometheus_client")
+        except ImportError as exc:
+            raise ProviderError(
+                "Prometheus requires 'prometheus-client'; install with "
+                "'pip install xyberos-observability[prometheus]'"
+            ) from exc
+        self._counter = prometheus_client.Counter(
+            self.METRIC_NAME,
+            "Xyberos events by name",
+            ["event"],
+            registry=self._registry,
+        )
+        return self._counter

xyberos_observability-0.1.0/xyberos_observability/sentry.py

@@ -0,0 +1,74 @@
+"""Sentry exporter — breadcrumbs for events, captures for failures (lazy SDK).
+
+The capture/breadcrumb functions are injectable so the mapping logic is fully
+testable without ``sentry-sdk``; when not injected the SDK is imported lazily.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from typing import Any, Callable
+
+from xyberos.events import BRAIN_ERROR, REQUEST_FAILED, Event
+from xyberos.exceptions.provider import ProviderError
+
+#: Callables injectable for tests (mirror sentry_sdk's add_breadcrumb/capture_message).
+AddBreadcrumb = Callable[[dict[str, Any]], None]
+CaptureMessage = Callable[[str], None]
+
+
+class SentryExporter:
+    """Adds a breadcrumb per event; captures failures as Sentry messages."""
+
+    _FAILURE_EVENTS = {REQUEST_FAILED, BRAIN_ERROR}
+
+    def __init__(
+        self,
+        *,
+        dsn: str | None = None,
+        add_breadcrumb: AddBreadcrumb | None = None,
+        capture_message: CaptureMessage | None = None,
+    ) -> None:
+        self._dsn = dsn if dsn is not None else os.getenv("SENTRY_DSN")
+        self._add_breadcrumb = add_breadcrumb
+        self._capture_message = capture_message
+
+    def export(self, event: Event) -> None:
+        if event.name in self._FAILURE_EVENTS:
+            self._capture(f"Xyberos {event.name}: {dict(event.data or {})}")
+        else:
+            self._breadcrumb(event)
+
+    def __call__(self, event: Event) -> None:
+        self.export(event)
+
+    def _breadcrumb(self, event: Event) -> None:
+        if self._add_breadcrumb is not None:
+            self._add_breadcrumb(
+                {"category": "xyberos.event", "message": event.name, "data": dict(event.data or {})}
+            )
+            return
+        self._ensure_sdk()
+        sentry_sdk.add_breadcrumb(category="xyberos.event", message=event.name, data=dict(event.data or {}))
+
+    def _capture(self, message: str) -> None:
+        if self._capture_message is not None:
+            self._capture_message(message)
+            return
+        self._ensure_sdk()
+        sentry_sdk.capture_message(message)
+
+    def _ensure_sdk(self) -> None:
+        global sentry_sdk  # noqa: PLW0603 - lazy module binding
+        if "sentry_sdk" not in globals():
+            try:
+                sentry_sdk = importlib.import_module("sentry_sdk")
+            except ImportError as exc:
+                raise ProviderError(
+                    "the 'sentry-sdk' package is required; install with "
+                    "'pip install xyberos-observability[sentry]'"
+                ) from exc
+            globals()["sentry_sdk"] = sentry_sdk
+            if self._dsn:
+                sentry_sdk.init(dsn=self._dsn, traces_sample_rate=1.0)

xyberos_observability-0.1.0/xyberos_observability.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: xyberos-observability
+Version: 0.1.0
+Summary: Observability exporters plugin (RFC-0019, M10): OTel, Prometheus, Langfuse, Sentry as thin EventBus exporters
+License: Apache-2.0
+Keywords: xyberos,plugin,observability,opentelemetry,prometheus,langfuse,sentry
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: xyberos>=1.0
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk; extra == "otel"
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client; extra == "prometheus"
+Provides-Extra: sentry
+Requires-Dist: sentry-sdk; extra == "sentry"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+
+# xyberos-observability (M10)
+
+Observability/telemetry exporters for Xyberos. Turns the runtime's event stream
+into traces and metrics for **OpenTelemetry**, **Prometheus**, **Langfuse**, and
+**Sentry** — satisfying RFC-0019 Track L, milestone M10.
+
+## Install
+
+```bash
+pip install -e ./observability
+```
+
+Optional extras:
+
+```bash
+pip install -e "./observability[otel]"      # opentelemetry-sdk (in-memory spans by default)
+pip install -e "./observability[prometheus]"# prometheus-client
+pip install -e "./observability[sentry]"    # sentry-sdk
+```
+
+## How it works
+
+Xyberos emits events (`runtime.request_started`, `brain.response_produced`,
+`memory.stored`, ...) on its `EventBus`. This plugin attaches an
+`EventRecorder` that forwards each event to the configured exporters:
+
+| Exporter | Destination | What it does |
+| --- | --- | --- |
+| `OpenTelemetryExporter` | OTel span pipeline | One span per event, named `event.name`, with `event.*` attributes (plus `event.prompt`). Defaults to an `InMemorySpanExporter` so traces are inspectable without a collector. |
+| `PrometheusExporter` | Prometheus registry | `xyberos_events_total{event="..."}` counter, one per event name. |
+| `LangfuseExporter` | Langfuse `/api/public/ingestion` | One `observation-create` item per event with `name`, `input` (prompt) and `output` (event data). Basic auth with `public_key:secret_key`. |
+| `SentryExporter` | Sentry SDK | Adds a breadcrumb per event; captures a message for failures (`runtime.request_failed`, `brain.error`). |
+
+## Usage
+
+```python
+from xyberos import create_app
+from xyberos_observability import ObservabilityPlugin, OpenTelemetryExporter
+
+app = create_app()
+app.load_plugin(ObservabilityPlugin(exporters=[OpenTelemetryExporter()]))
+
+reply = app.chat("hello")          # emits events -> spans
+```
+
+Select exporters by environment variable (comma-separated) instead:
+
+```bash
+export OBSERVABILITY_EXPORTERS=otel,prometheus,langfuse,sentry
+```
+
+```python
+from xyberos_observability import ObservabilityPlugin
+
+app.load_plugin(ObservabilityPlugin())
+```
+
+For Langfuse, set `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY` and
+`LANGFUSE_HOST` (defaults `https://cloud.langfuse.com`).
+
+## Example
+
+```bash
+python examples/trace_a_chat.py                       # inspect in-memory spans
+python examples/trace_a_chat.py --prometheus          # also track a counter
+python examples/trace_a_chat.py --langfuse            # POST traces to Langfuse
+```
+
+## Tests
+
+```bash
+python -m pytest observability/tests -q
+```
+
+Tests use injectable transports / in-memory exporters, so nothing touches the
+network or a real collector. The DoD test (`tests/test_plugin.py`) runs
+`app.chat(...)` and asserts a trace lands in OTel and Langfuse.

xyberos_observability-0.1.0/xyberos_observability.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+tests/test_langfuse.py
+tests/test_otel.py
+tests/test_plugin.py
+tests/test_prometheus.py
+tests/test_sentry.py
+xyberos_observability/__init__.py
+xyberos_observability/http.py
+xyberos_observability/langfuse.py
+xyberos_observability/otel.py
+xyberos_observability/plugin.py
+xyberos_observability/prometheus.py
+xyberos_observability/sentry.py
+xyberos_observability.egg-info/PKG-INFO
+xyberos_observability.egg-info/SOURCES.txt
+xyberos_observability.egg-info/dependency_links.txt
+xyberos_observability.egg-info/entry_points.txt
+xyberos_observability.egg-info/requires.txt
+xyberos_observability.egg-info/top_level.txt

xyberos_observability-0.1.0/xyberos_observability.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

xyberos_observability-0.1.0/xyberos_observability.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[xyberos.plugins]
+observability = xyberos_observability.plugin:plugin

xyberos_observability-0.1.0/xyberos_observability.egg-info/requires.txt

@@ -0,0 +1,13 @@
+xyberos>=1.0
+
+[otel]
+opentelemetry-sdk
+
+[prometheus]
+prometheus-client
+
+[sentry]
+sentry-sdk
+
+[test]
+pytest

xyberos_observability-0.1.0/xyberos_observability.egg-info/top_level.txt

@@ -0,0 +1 @@
+xyberos_observability