cogno-observability 0.1.0__tar.gz

cogno_observability-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Sudoers AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cogno_observability-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: cogno-observability
+Version: 0.1.0
+Summary: SRE/Ops monitoring for the Cogno stack — Prometheus metrics sink + /metrics wiring + Grafana dashboards/alerts. Cross-tenant fleet health (NOT the tenant-facing Radar Tokens; NOT billing).
+Author: Vinicius Vale
+Maintainer: Sudoers AI
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prometheus-client>=0.20
+Provides-Extra: http
+Requires-Dist: prometheus-fastapi-instrumentator>=7.0; extra == "http"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: prometheus-fastapi-instrumentator>=7.0; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# cogno-observability
+
+**SRE/Ops monitoring for the [Cogno](https://github.com/sudoers-ai/cogno-anima) stack** — a Prometheus metrics sink + `/metrics` wiring + Grafana dashboards/alerts, plus a one-login deploy stack for metrics **and** live logs.
+
+Where [`cogno-anima`](https://github.com/sudoers-ai/cogno-anima) is the *mind* and [`cogno-homeo`](https://github.com/sudoers-ai/cogno-homeo) keeps the calls *alive*, `cogno-observability` is the **operator's eyes** on the running fleet — how many turns, how fast, how much they cost, where they fail. It attaches to the host from *outside* its cognition, so the host never imports `prometheus_client`.
+
+> Status: **alpha** — metrics sink + `/metrics` wiring + deploy stack + unit/contract suite in place.
+
+SRE/Ops monitoring is the *operator-facing* pillar — cross-tenant fleet health — and is
+deliberately **separate** from two other consumers of the same turn data:
+
+| Surface | Audience | This repo? |
+|---|---|---|
+| **Fleet monitoring** (Prometheus/Grafana, cross-tenant) | operator / SRE | ✅ **yes** |
+| **Radar Tokens** (per-tenant usage, from the `token_ledger`) | the tenant/customer | ❌ cogno-ui |
+| **Billing / BudgetGuard** (quota, spend) | the platform | ❌ cogno-host + cogno-meter |
+
+## Why a separate repo
+
+The house rule is **libs emit, host configures** — and the host stays **prometheus-agnostic**. It
+emits one `TurnEvent` per turn to an injected `MetricsSink` and exposes an `instrument(app)` hook;
+it never imports `prometheus_client`. This package fills both seams, so the Prometheus dependency,
+the metric catalog, and the dashboards live here — swappable, versioned independently, and absent
+from a deployment that doesn't want them.
+
+## Logs ≠ metrics
+
+Two different pipelines. **Logs** (host `configure_logging` → stdout → Loki/ELK) answer *"what
+happened in this turn?"* and may carry high-cardinality `tenant`/`identity`/`session`. **Metrics**
+(this repo) answer *"how is the fleet doing?"* — aggregate series with **low-cardinality labels
+only**. `session_id`/`identity_id` are **never** Prometheus labels (they'd blow up the TSDB); use
+logs for per-turn tracing. `tenant` is opt-in and capped (`PrometheusMetricsSink(tenant_label=True)`).
+
+## Install
+
+```bash
+pip install cogno-observability            # core (prometheus-client)
+pip install "cogno-observability[http]"    # + per-route HTTP RED metrics (fastapi instrumentator)
+```
+
+## Wire it into the host
+
+```python
+from cogno_host.api.pg_app import create_pg_app
+from cogno_observability import PrometheusMetricsSink, attach
+
+app = create_pg_app(
+    dsn, auth=admin,
+    metrics_sink=PrometheusMetricsSink(),   # per-turn TurnEvent → Prometheus series
+    instrument=attach,                      # mounts /metrics + HTTP instrumentation
+)
+```
+
+With neither argument the host runs exactly as before (no-op sink, no `/metrics`).
+
+## Metrics
+
+| Metric | Type | Labels | Meaning |
+|---|---|---|---|
+| `cogno_turns_total` | counter | route, stop_reason, ok, blocked, cache_hit | turn outcomes |
+| `cogno_turn_errors_total` | counter | error | unhandled exceptions (by class) |
+| `cogno_turn_duration_seconds` | histogram | route | end-to-end latency |
+| `cogno_stage_duration_seconds` | histogram | stage | per cognitive-stage latency |
+| `cogno_stage_tokens_total` | counter | stage, model, direction | tokens (in/out/embedding) |
+| `cogno_cost_usd_total` | counter | — | provider spend (0 for local) |
+| `cogno_drift_score` | histogram | — | cumulative drift distribution |
+| `cogno_drift_actions_total` | counter | action | drift-triggered actions |
+| `cogno_tool_calls_total` / `_failures_total` | counter | — | EGO tool calls / failures |
+| `cogno_failovers_total`, `cogno_self_corrections_total`, `cogno_handoffs_total` | counter | — | reliability |
+| `cogno_blocked_total` | counter | stop_reason | safety/quota/PII blocks |
+
+Plus HTTP RED metrics (`http_request_*`) from the instrumentator.
+
+## Multi-worker
+
+Each uvicorn/gunicorn worker has its own registry. Set `PROMETHEUS_MULTIPROC_DIR` to a shared
+(empty at boot) dir and `attach` will reconcile across workers via `MultiProcessCollector` at scrape
+time. Without it, single-process mode is used.
+
+## Ops assets (`ops/`)
+
+- `alerts/cogno_rules.yml` — Prometheus recording + alerting rules.
+- `dashboards/cogno_overview.json` — Grafana dashboard (import, pick your Prometheus datasource).
+- `dashboards/cogno_logs.json` — Grafana dashboard for live logs (Loki).
+- `prometheus-scrape.example.yml` — scrape config / ServiceMonitor example.
+- `SLOs.md` — starting SLOs + a metric→runbook map.
+
+## Deploy — one Grafana login for metrics + logs
+
+`deploy/` is a docker-compose stack (Prometheus + Loki + Promtail + Grafana) that watches an
+existing host and gives you **one Grafana login** to follow it live — metrics and near-real-time
+logs on the same pane. See [`deploy/README.md`](deploy/README.md).
+
+## Host integration
+
+The host exposes two seams (`metrics_sink=` + `instrument(app)`) and stays prometheus-agnostic;
+this library fills them. See [`docs/HOST_INTEGRATION.md`](docs/HOST_INTEGRATION.md).
+
+## The Cogno ecosystem
+
+`cogno-observability` is one organ of **[Cogno](https://github.com/sudoers-ai)** — a family of
+small, composable, Apache-2.0 libraries that together form a complete conversational-agent
+platform. Each library owns a single concern and stays infra-agnostic; a **host** assembles them
+into a running agent:
+
+![The Cogno ecosystem](docs/assets/cogno-ecosystem.svg)
+
+The open-source libraries are the organs; the **host is the body** that joins them. Our reference
+host — `cogno-host`, with its `cogno-ui` dashboard — is the private product layer, but it holds no
+special powers: everything it does rides on the public seams documented in each library's
+`docs/HOST_INTEGRATION.md`.

cogno_observability-0.1.0/README.md

@@ -0,0 +1,111 @@
+# cogno-observability
+
+**SRE/Ops monitoring for the [Cogno](https://github.com/sudoers-ai/cogno-anima) stack** — a Prometheus metrics sink + `/metrics` wiring + Grafana dashboards/alerts, plus a one-login deploy stack for metrics **and** live logs.
+
+Where [`cogno-anima`](https://github.com/sudoers-ai/cogno-anima) is the *mind* and [`cogno-homeo`](https://github.com/sudoers-ai/cogno-homeo) keeps the calls *alive*, `cogno-observability` is the **operator's eyes** on the running fleet — how many turns, how fast, how much they cost, where they fail. It attaches to the host from *outside* its cognition, so the host never imports `prometheus_client`.
+
+> Status: **alpha** — metrics sink + `/metrics` wiring + deploy stack + unit/contract suite in place.
+
+SRE/Ops monitoring is the *operator-facing* pillar — cross-tenant fleet health — and is
+deliberately **separate** from two other consumers of the same turn data:
+
+| Surface | Audience | This repo? |
+|---|---|---|
+| **Fleet monitoring** (Prometheus/Grafana, cross-tenant) | operator / SRE | ✅ **yes** |
+| **Radar Tokens** (per-tenant usage, from the `token_ledger`) | the tenant/customer | ❌ cogno-ui |
+| **Billing / BudgetGuard** (quota, spend) | the platform | ❌ cogno-host + cogno-meter |
+
+## Why a separate repo
+
+The house rule is **libs emit, host configures** — and the host stays **prometheus-agnostic**. It
+emits one `TurnEvent` per turn to an injected `MetricsSink` and exposes an `instrument(app)` hook;
+it never imports `prometheus_client`. This package fills both seams, so the Prometheus dependency,
+the metric catalog, and the dashboards live here — swappable, versioned independently, and absent
+from a deployment that doesn't want them.
+
+## Logs ≠ metrics
+
+Two different pipelines. **Logs** (host `configure_logging` → stdout → Loki/ELK) answer *"what
+happened in this turn?"* and may carry high-cardinality `tenant`/`identity`/`session`. **Metrics**
+(this repo) answer *"how is the fleet doing?"* — aggregate series with **low-cardinality labels
+only**. `session_id`/`identity_id` are **never** Prometheus labels (they'd blow up the TSDB); use
+logs for per-turn tracing. `tenant` is opt-in and capped (`PrometheusMetricsSink(tenant_label=True)`).
+
+## Install
+
+```bash
+pip install cogno-observability            # core (prometheus-client)
+pip install "cogno-observability[http]"    # + per-route HTTP RED metrics (fastapi instrumentator)
+```
+
+## Wire it into the host
+
+```python
+from cogno_host.api.pg_app import create_pg_app
+from cogno_observability import PrometheusMetricsSink, attach
+
+app = create_pg_app(
+    dsn, auth=admin,
+    metrics_sink=PrometheusMetricsSink(),   # per-turn TurnEvent → Prometheus series
+    instrument=attach,                      # mounts /metrics + HTTP instrumentation
+)
+```
+
+With neither argument the host runs exactly as before (no-op sink, no `/metrics`).
+
+## Metrics
+
+| Metric | Type | Labels | Meaning |
+|---|---|---|---|
+| `cogno_turns_total` | counter | route, stop_reason, ok, blocked, cache_hit | turn outcomes |
+| `cogno_turn_errors_total` | counter | error | unhandled exceptions (by class) |
+| `cogno_turn_duration_seconds` | histogram | route | end-to-end latency |
+| `cogno_stage_duration_seconds` | histogram | stage | per cognitive-stage latency |
+| `cogno_stage_tokens_total` | counter | stage, model, direction | tokens (in/out/embedding) |
+| `cogno_cost_usd_total` | counter | — | provider spend (0 for local) |
+| `cogno_drift_score` | histogram | — | cumulative drift distribution |
+| `cogno_drift_actions_total` | counter | action | drift-triggered actions |
+| `cogno_tool_calls_total` / `_failures_total` | counter | — | EGO tool calls / failures |
+| `cogno_failovers_total`, `cogno_self_corrections_total`, `cogno_handoffs_total` | counter | — | reliability |
+| `cogno_blocked_total` | counter | stop_reason | safety/quota/PII blocks |
+
+Plus HTTP RED metrics (`http_request_*`) from the instrumentator.
+
+## Multi-worker
+
+Each uvicorn/gunicorn worker has its own registry. Set `PROMETHEUS_MULTIPROC_DIR` to a shared
+(empty at boot) dir and `attach` will reconcile across workers via `MultiProcessCollector` at scrape
+time. Without it, single-process mode is used.
+
+## Ops assets (`ops/`)
+
+- `alerts/cogno_rules.yml` — Prometheus recording + alerting rules.
+- `dashboards/cogno_overview.json` — Grafana dashboard (import, pick your Prometheus datasource).
+- `dashboards/cogno_logs.json` — Grafana dashboard for live logs (Loki).
+- `prometheus-scrape.example.yml` — scrape config / ServiceMonitor example.
+- `SLOs.md` — starting SLOs + a metric→runbook map.
+
+## Deploy — one Grafana login for metrics + logs
+
+`deploy/` is a docker-compose stack (Prometheus + Loki + Promtail + Grafana) that watches an
+existing host and gives you **one Grafana login** to follow it live — metrics and near-real-time
+logs on the same pane. See [`deploy/README.md`](deploy/README.md).
+
+## Host integration
+
+The host exposes two seams (`metrics_sink=` + `instrument(app)`) and stays prometheus-agnostic;
+this library fills them. See [`docs/HOST_INTEGRATION.md`](docs/HOST_INTEGRATION.md).
+
+## The Cogno ecosystem
+
+`cogno-observability` is one organ of **[Cogno](https://github.com/sudoers-ai)** — a family of
+small, composable, Apache-2.0 libraries that together form a complete conversational-agent
+platform. Each library owns a single concern and stays infra-agnostic; a **host** assembles them
+into a running agent:
+
+![The Cogno ecosystem](docs/assets/cogno-ecosystem.svg)
+
+The open-source libraries are the organs; the **host is the body** that joins them. Our reference
+host — `cogno-host`, with its `cogno-ui` dashboard — is the private product layer, but it holds no
+special powers: everything it does rides on the public seams documented in each library's
+`docs/HOST_INTEGRATION.md`.

cogno_observability-0.1.0/cogno_observability/__init__.py

@@ -0,0 +1,22 @@
+"""cogno-observability — SRE/Ops monitoring for the Cogno stack.
+
+The **operator-facing** half of observability (cross-tenant fleet health), separate from the
+**tenant-facing** Radar Tokens in cogno-ui and from billing. The host stays prometheus-agnostic
+and exposes two seams; this package fills them:
+
+* :class:`PrometheusMetricsSink` — implements the host's ``MetricsSink`` (``record(TurnEvent)``),
+  turning each turn into Prometheus time-series.
+* :func:`attach` — the ``instrument(app)`` hook that mounts ``/metrics`` + HTTP RED metrics.
+
+    from cogno_observability import PrometheusMetricsSink, attach
+    app = create_pg_app(dsn, auth=admin, metrics_sink=PrometheusMetricsSink(), instrument=attach)
+
+Grafana dashboards + Prometheus alert/recording rules live under ``ops/``.
+"""
+
+from cogno_observability.instrument import attach
+from cogno_observability.metrics import Metrics
+from cogno_observability.sink import PrometheusMetricsSink, TurnEventLike
+
+__all__ = ["PrometheusMetricsSink", "attach", "Metrics", "TurnEventLike"]
+__version__ = "0.1.0"

cogno_observability-0.1.0/cogno_observability/instrument.py

@@ -0,0 +1,64 @@
+"""``attach(app)`` — the host's ``instrument`` hook: mount ``/metrics`` + HTTP RED instrumentation.
+
+Passed to ``create_pg_app(..., instrument=attach)``. The host calls it right after building the
+FastAPI app (before routers), so it wraps every route. Keeping this here — not in the host — is
+the whole point of the split: the host never imports ``prometheus_client``.
+
+**Multiprocess (N uvicorn/gunicorn workers).** Each worker has its own in-process registry, so a
+naive ``/metrics`` would report only the scraped worker's slice. When ``PROMETHEUS_MULTIPROC_DIR``
+is set, prometheus_client writes counters to that shared dir and the exposition endpoint reconciles
+across workers via ``MultiProcessCollector``. Set the env var and ensure the dir exists/empty at
+boot (per the prometheus_client docs). Without it, single-process mode is used (dev / one worker).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+log = logging.getLogger("cogno_observability.instrument")
+
+_EXCLUDED = ("/metrics", "/health")
+
+
+def attach(app: Any, *, metrics_path: str = "/metrics", instrument_http: bool = True) -> None:
+    """Mount ``metrics_path`` on ``app`` and (optionally) add per-route HTTP RED metrics.
+
+    Best-effort and idempotent-ish: a missing optional dep degrades gracefully (business metrics
+    still work; only the HTTP layer is skipped)."""
+    if instrument_http:
+        try:
+            from prometheus_fastapi_instrumentator import Instrumentator
+            Instrumentator(
+                should_group_status_codes=False,
+                should_ignore_untemplated=True,
+                excluded_handlers=list(_EXCLUDED),
+            ).instrument(app)   # records default http_request_* to the global REGISTRY
+            log.info("event=http_instrumented")
+        except ImportError:
+            log.warning("event=http_instrument_skipped reason=prometheus-fastapi-instrumentator "
+                        "not installed (pip install 'cogno-observability[http]')")
+
+    app.mount(metrics_path, _metrics_asgi_app())
+    log.info("event=metrics_mounted path=%s multiprocess=%s",
+             metrics_path, bool(os.environ.get("PROMETHEUS_MULTIPROC_DIR")))
+
+
+def _metrics_asgi_app() -> Any:
+    """Build the ``/metrics`` ASGI app — a multiprocess-reconciling registry when configured,
+    else the default global registry."""
+    from prometheus_client import make_asgi_app
+    mpdir = os.environ.get("PROMETHEUS_MULTIPROC_DIR")
+    if mpdir:
+        # prometheus_client requires the dir to EXIST and be emptied at process start (stale files
+        # from a previous run would be summed into the exposition). We can't empty it here safely
+        # (sibling workers may already be writing), but we can catch the common misconfiguration.
+        if not os.path.isdir(mpdir):
+            log.warning("event=multiproc_dir_missing dir=%s — /metrics will under-report; create it "
+                        "and empty it at boot (per PROMETHEUS_MULTIPROC_DIR docs)", mpdir)
+        from prometheus_client import CollectorRegistry, multiprocess
+        registry = CollectorRegistry()
+        multiprocess.MultiProcessCollector(registry)
+        return make_asgi_app(registry=registry)
+    return make_asgi_app()

cogno_observability-0.1.0/cogno_observability/metrics.py

@@ -0,0 +1,114 @@
+"""Prometheus metric definitions for the Cogno pipeline (business/SRE layer).
+
+These live in a **separate Ops repo** (not cogno-host, not cogno-ui): the host stays
+prometheus-agnostic and only emits a ``TurnEvent`` per turn to an injected ``MetricsSink``; this
+module is where those events become time-series scraped into Grafana.
+
+**Cardinality discipline (the cardinal rule of Prometheus):** every label here is a *bounded*
+set — ``route`` (~4), ``stop_reason`` (~8), ``stage`` (~6), ``model`` (the deployment's catalog),
+``direction`` (3), ``action`` (4), ``error`` (exception class names). High-cardinality identifiers
+(``session_id`` / ``identity_id``) are **deliberately absent** — they belong in logs (Loki), never
+as labels, or they blow up the TSDB. ``tenant`` is opt-in and capped (see :class:`sink` config)
+because a large multi-tenant fleet is still unbounded.
+
+Adapted from the parent monolith's ``cogno/core/metrics.py``, but fed off the decomposed host's
+``TurnEvent`` DTO instead of reaching into a ``PipelineContext`` (whose field names differ).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from prometheus_client import REGISTRY, CollectorRegistry, Counter, Histogram
+
+
+def _get_or_create(reg: CollectorRegistry, name: str, factory: Callable[[], Any]) -> Any:
+    """Create a metric, or return the one already registered under ``name`` on ``reg``.
+
+    prometheus_client raises ``ValueError: Duplicated timeseries`` if a name is registered twice on
+    the same registry, so constructing a second ``Metrics``/``PrometheusMetricsSink`` on the default
+    ``REGISTRY`` (gunicorn --preload + fork, an app factory reused across tests, a hot reload) would
+    crash at boot. Reuse the existing collector instead — two sinks on one registry then share the
+    same series, which is exactly right for a process-global registry."""
+    try:
+        return factory()
+    except ValueError:
+        existing = getattr(reg, "_names_to_collectors", {}).get(name)
+        if existing is None:
+            raise
+        return existing
+
+
+# Latency buckets (seconds) tuned for LLM turns: sub-second cache hits → multi-minute agent loops.
+_TURN_BUCKETS = (0.25, 0.5, 1, 2, 5, 10, 20, 30, 60, 120, 300)
+_STAGE_BUCKETS = (0.05, 0.1, 0.25, 0.5, 1, 2, 5, 10, 30, 60)
+_DRIFT_BUCKETS = (0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0)
+
+
+class Metrics:
+    """The Cogno metric set, bound to one registry (default: the global one).
+
+    Held on an instance rather than module globals so tests get a fresh registry each time and a
+    multiprocess deployment can pass its own. All names are prefixed ``cogno_`` and carry a HELP
+    string (Grafana/alerts reference them by name)."""
+
+    def __init__(self, registry: CollectorRegistry | None = None) -> None:
+        # NB: prometheus_client treats ``registry=None`` as "register nowhere" (not "the default"),
+        # so resolve None to the global REGISTRY explicitly.
+        reg = registry if registry is not None else REGISTRY
+
+        def counter(name: str, doc: str, labels: list[str] | None = None) -> Any:
+            return _get_or_create(reg, name, lambda: Counter(
+                name, doc, labels or [], registry=reg))
+
+        def histogram(name: str, doc: str, buckets: tuple,
+                      labels: list[str] | None = None) -> Any:
+            return _get_or_create(reg, name, lambda: Histogram(
+                name, doc, labels or [], buckets=buckets, registry=reg))
+
+        # ── turn outcomes ────────────────────────────────────────────────────────────────
+        self.turns_total = counter(
+            "cogno_turns_total", "Pipeline turns by outcome",
+            ["route", "stop_reason", "ok", "blocked", "cache_hit"])
+        self.turn_errors_total = counter(
+            "cogno_turn_errors_total", "Turns that raised an unhandled exception", ["error"])
+        self.turn_duration_seconds = histogram(
+            "cogno_turn_duration_seconds", "End-to-end turn latency", _TURN_BUCKETS, ["route"])
+
+        # ── per-stage cost ───────────────────────────────────────────────────────────────
+        self.stage_duration_seconds = histogram(
+            "cogno_stage_duration_seconds", "Per cognitive-stage latency", _STAGE_BUCKETS, ["stage"])
+        self.stage_tokens_total = counter(
+            "cogno_stage_tokens_total", "Tokens consumed per stage/model",
+            ["stage", "model", "direction"])  # direction: in|out|embedding
+        self.cost_usd_total = counter(
+            "cogno_cost_usd_total", "Provider cost in USD (0 for local models)")
+
+        # ── quality / reliability signals ────────────────────────────────────────────────
+        self.drift_score = histogram(
+            "cogno_drift_score", "Cumulative drift score distribution", _DRIFT_BUCKETS)
+        self.drift_actions_total = counter(
+            "cogno_drift_actions_total", "Drift-triggered actions",
+            ["action"])  # none|warn|ask_user|self_correct
+        self.tool_calls_total = counter(
+            "cogno_tool_calls_total", "EGO tool executions")
+        self.tool_failures_total = counter(
+            "cogno_tool_failures_total", "EGO tool executions that returned ok=False")
+        self.failovers_total = counter(
+            "cogno_failovers_total", "LLM backend failover events")
+        self.self_corrections_total = counter(
+            "cogno_self_corrections_total", "EGO↔SUPEREGO correction retries")
+        self.handoffs_total = counter(
+            "cogno_handoffs_total", "Turns escalated to a human handoff")
+
+        # ── protection nets (the anti-fabrication layers; see cogno-host grounding.py /
+        #    provenance.py) — a rising rate = a model/vertical regressing upstream ──────────
+        self.grounding_rewrites_total = counter(
+            "cogno_grounding_rewrites_total",
+            "Replies rewritten by the grounding backstop, by rule; repaired=true means the "
+            "repair re-step delivered the real answer", ["rule", "repaired"])
+        self.provenance_refusals_total = counter(
+            "cogno_provenance_refusals_total",
+            "Stale-id writes refused by the id-provenance guard (absorbed in the EGO loop)")
+        self.blocked_total = counter(
+            "cogno_blocked_total", "Turns blocked (safety/quota/PII)", ["stop_reason"])

cogno_observability-0.1.0/cogno_observability/sink.py

@@ -0,0 +1,158 @@
+"""``PrometheusMetricsSink`` — translate a host ``TurnEvent`` into Prometheus time-series.
+
+This is the concrete implementation of the host's ``MetricsSink`` protocol (``record(event)``).
+It is **duck-typed** against the event — it reads attributes off it and never imports
+``cogno_host``, so the Ops layer stays decoupled from the product repo (any host emitting the same
+``TurnEvent`` shape is observable). The host injects it:
+
+    from cogno_observability import PrometheusMetricsSink, attach
+    app = create_pg_app(dsn, auth=admin,
+                        metrics_sink=PrometheusMetricsSink(), instrument=attach)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional, Protocol, runtime_checkable
+
+from prometheus_client import CollectorRegistry
+
+from cogno_observability.metrics import Metrics, _get_or_create
+
+log = logging.getLogger("cogno_observability.sink")
+
+
+@runtime_checkable
+class TurnEventLike(Protocol):
+    """The subset of the host's ``TurnEvent`` this sink reads (documentation + typing only)."""
+
+    tenant_id: str
+    route: str
+    stop_reason: str
+    total_tokens: int
+    elapsed_ms: float
+    cache_hit: bool
+    blocked: bool
+    ok: bool
+    error: str
+    cost_usd: float
+    drift_cumulative: float
+    drift_action: str
+    tool_calls: int
+    tool_failures: int
+    failover_count: int
+    correction_count: int
+    handoff: bool
+    stages: list
+
+
+def _b(v: Any) -> str:
+    """Prometheus label values must be strings — normalize a bool to a stable lowercase token."""
+    return "true" if bool(v) else "false"
+
+
+class PrometheusMetricsSink:
+    """A ``MetricsSink`` that records each turn to Prometheus counters/histograms.
+
+    ``record`` is **best-effort**: monitoring must never break a turn, so any error while recording
+    is swallowed with a warning (the parent did the same). Set ``tenant_label=True`` ONLY on a
+    small/bounded fleet — it adds a ``tenant`` label to the turn counter (unbounded tenants would
+    explode cardinality; off by default)."""
+
+    def __init__(self, *, registry: Optional[CollectorRegistry] = None,
+                 tenant_label: bool = False) -> None:
+        self._m = Metrics(registry)
+        self._tenant_label = tenant_label
+        if tenant_label:
+            # A separate, opt-in counter carrying the tenant dimension (kept off the main
+            # counters so their cardinality stays flat). ``registry=None`` → the global REGISTRY;
+            # get-or-create so a second sink on that registry reuses it instead of crashing.
+            from prometheus_client import REGISTRY, Counter
+            reg = registry if registry is not None else REGISTRY
+            self._turns_by_tenant = _get_or_create(
+                reg, "cogno_turns_by_tenant_total", lambda: Counter(
+                    "cogno_turns_by_tenant_total", "Turns per tenant (bounded fleets only)",
+                    ["tenant", "ok"], registry=reg))
+
+    def record(self, event: TurnEventLike) -> None:
+        try:
+            self._record(event)
+        except Exception as exc:  # noqa: BLE001 — observability must not break the turn
+            log.warning("event=metrics_record_failed error=%s", exc)
+
+    def _record(self, e: Any) -> None:
+        m = self._m
+        route = getattr(e, "route", "") or "none"
+        stop_reason = getattr(e, "stop_reason", "") or "completed"
+        ok = getattr(e, "ok", True)
+        blocked = getattr(e, "blocked", False)
+        cache_hit = getattr(e, "cache_hit", False)
+
+        m.turns_total.labels(route=route, stop_reason=stop_reason, ok=_b(ok),
+                             blocked=_b(blocked), cache_hit=_b(cache_hit)).inc()
+        if self._tenant_label:
+            self._turns_by_tenant.labels(tenant=getattr(e, "tenant_id", "") or "unknown",
+                                         ok=_b(ok)).inc()
+
+        if not ok:
+            m.turn_errors_total.labels(error=getattr(e, "error", "") or "unknown").inc()
+        if blocked:
+            m.blocked_total.labels(stop_reason=stop_reason).inc()
+
+        elapsed_ms = float(getattr(e, "elapsed_ms", 0.0) or 0.0)
+        if elapsed_ms > 0:
+            m.turn_duration_seconds.labels(route=route).observe(elapsed_ms / 1000.0)
+
+        # ── per-stage breakdown ──────────────────────────────────────────────────────────
+        for s in getattr(e, "stages", None) or []:
+            stage = getattr(s, "stage", "") or "unknown"
+            model = getattr(s, "model", "") or "unknown"
+            s_ms = float(getattr(s, "elapsed_ms", 0.0) or 0.0)
+            if s_ms > 0:
+                m.stage_duration_seconds.labels(stage=stage).observe(s_ms / 1000.0)
+            tin = int(getattr(s, "tokens_in", 0) or 0)
+            tout = int(getattr(s, "tokens_out", 0) or 0)
+            temb = int(getattr(s, "embedding_tokens", 0) or 0)
+            if tin:
+                m.stage_tokens_total.labels(stage=stage, model=model, direction="in").inc(tin)
+            if tout:
+                m.stage_tokens_total.labels(stage=stage, model=model, direction="out").inc(tout)
+            if temb:
+                m.stage_tokens_total.labels(stage=stage, model=model,
+                                            direction="embedding").inc(temb)
+
+        cost = float(getattr(e, "cost_usd", 0.0) or 0.0)
+        if cost > 0:
+            m.cost_usd_total.inc(cost)
+
+        # ── quality / reliability ────────────────────────────────────────────────────────
+        drift = float(getattr(e, "drift_cumulative", 0.0) or 0.0)
+        if drift > 0:
+            m.drift_score.observe(drift)
+        action = getattr(e, "drift_action", "") or ""
+        if action:
+            m.drift_actions_total.labels(action=action).inc()
+
+        tool_calls = int(getattr(e, "tool_calls", 0) or 0)
+        if tool_calls:
+            m.tool_calls_total.inc(tool_calls)
+        tool_failures = int(getattr(e, "tool_failures", 0) or 0)
+        if tool_failures:
+            m.tool_failures_total.inc(tool_failures)
+        failovers = int(getattr(e, "failover_count", 0) or 0)
+        if failovers:
+            m.failovers_total.inc(failovers)
+        corrections = int(getattr(e, "correction_count", 0) or 0)
+        if corrections:
+            m.self_corrections_total.inc(corrections)
+        if getattr(e, "handoff", False):
+            m.handoffs_total.inc()
+        # protection nets (see cogno-host grounding.py / provenance.py)
+        grounding_rule = getattr(e, "grounding_rule", "") or ""
+        if grounding_rule:
+            m.grounding_rewrites_total.labels(
+                rule=grounding_rule,
+                repaired=_b(getattr(e, "grounding_repaired", False))).inc()
+        provenance_refusals = int(getattr(e, "provenance_refusals", 0) or 0)
+        if provenance_refusals:
+            m.provenance_refusals_total.inc(provenance_refusals)

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

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: cogno-observability
+Version: 0.1.0
+Summary: SRE/Ops monitoring for the Cogno stack — Prometheus metrics sink + /metrics wiring + Grafana dashboards/alerts. Cross-tenant fleet health (NOT the tenant-facing Radar Tokens; NOT billing).
+Author: Vinicius Vale
+Maintainer: Sudoers AI
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: prometheus-client>=0.20
+Provides-Extra: http
+Requires-Dist: prometheus-fastapi-instrumentator>=7.0; extra == "http"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: prometheus-fastapi-instrumentator>=7.0; extra == "dev"
+Requires-Dist: fastapi>=0.110; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# cogno-observability
+
+**SRE/Ops monitoring for the [Cogno](https://github.com/sudoers-ai/cogno-anima) stack** — a Prometheus metrics sink + `/metrics` wiring + Grafana dashboards/alerts, plus a one-login deploy stack for metrics **and** live logs.
+
+Where [`cogno-anima`](https://github.com/sudoers-ai/cogno-anima) is the *mind* and [`cogno-homeo`](https://github.com/sudoers-ai/cogno-homeo) keeps the calls *alive*, `cogno-observability` is the **operator's eyes** on the running fleet — how many turns, how fast, how much they cost, where they fail. It attaches to the host from *outside* its cognition, so the host never imports `prometheus_client`.
+
+> Status: **alpha** — metrics sink + `/metrics` wiring + deploy stack + unit/contract suite in place.
+
+SRE/Ops monitoring is the *operator-facing* pillar — cross-tenant fleet health — and is
+deliberately **separate** from two other consumers of the same turn data:
+
+| Surface | Audience | This repo? |
+|---|---|---|
+| **Fleet monitoring** (Prometheus/Grafana, cross-tenant) | operator / SRE | ✅ **yes** |
+| **Radar Tokens** (per-tenant usage, from the `token_ledger`) | the tenant/customer | ❌ cogno-ui |
+| **Billing / BudgetGuard** (quota, spend) | the platform | ❌ cogno-host + cogno-meter |
+
+## Why a separate repo
+
+The house rule is **libs emit, host configures** — and the host stays **prometheus-agnostic**. It
+emits one `TurnEvent` per turn to an injected `MetricsSink` and exposes an `instrument(app)` hook;
+it never imports `prometheus_client`. This package fills both seams, so the Prometheus dependency,
+the metric catalog, and the dashboards live here — swappable, versioned independently, and absent
+from a deployment that doesn't want them.
+
+## Logs ≠ metrics
+
+Two different pipelines. **Logs** (host `configure_logging` → stdout → Loki/ELK) answer *"what
+happened in this turn?"* and may carry high-cardinality `tenant`/`identity`/`session`. **Metrics**
+(this repo) answer *"how is the fleet doing?"* — aggregate series with **low-cardinality labels
+only**. `session_id`/`identity_id` are **never** Prometheus labels (they'd blow up the TSDB); use
+logs for per-turn tracing. `tenant` is opt-in and capped (`PrometheusMetricsSink(tenant_label=True)`).
+
+## Install
+
+```bash
+pip install cogno-observability            # core (prometheus-client)
+pip install "cogno-observability[http]"    # + per-route HTTP RED metrics (fastapi instrumentator)
+```
+
+## Wire it into the host
+
+```python
+from cogno_host.api.pg_app import create_pg_app
+from cogno_observability import PrometheusMetricsSink, attach
+
+app = create_pg_app(
+    dsn, auth=admin,
+    metrics_sink=PrometheusMetricsSink(),   # per-turn TurnEvent → Prometheus series
+    instrument=attach,                      # mounts /metrics + HTTP instrumentation
+)
+```
+
+With neither argument the host runs exactly as before (no-op sink, no `/metrics`).
+
+## Metrics
+
+| Metric | Type | Labels | Meaning |
+|---|---|---|---|
+| `cogno_turns_total` | counter | route, stop_reason, ok, blocked, cache_hit | turn outcomes |
+| `cogno_turn_errors_total` | counter | error | unhandled exceptions (by class) |
+| `cogno_turn_duration_seconds` | histogram | route | end-to-end latency |
+| `cogno_stage_duration_seconds` | histogram | stage | per cognitive-stage latency |
+| `cogno_stage_tokens_total` | counter | stage, model, direction | tokens (in/out/embedding) |
+| `cogno_cost_usd_total` | counter | — | provider spend (0 for local) |
+| `cogno_drift_score` | histogram | — | cumulative drift distribution |
+| `cogno_drift_actions_total` | counter | action | drift-triggered actions |
+| `cogno_tool_calls_total` / `_failures_total` | counter | — | EGO tool calls / failures |
+| `cogno_failovers_total`, `cogno_self_corrections_total`, `cogno_handoffs_total` | counter | — | reliability |
+| `cogno_blocked_total` | counter | stop_reason | safety/quota/PII blocks |
+
+Plus HTTP RED metrics (`http_request_*`) from the instrumentator.
+
+## Multi-worker
+
+Each uvicorn/gunicorn worker has its own registry. Set `PROMETHEUS_MULTIPROC_DIR` to a shared
+(empty at boot) dir and `attach` will reconcile across workers via `MultiProcessCollector` at scrape
+time. Without it, single-process mode is used.
+
+## Ops assets (`ops/`)
+
+- `alerts/cogno_rules.yml` — Prometheus recording + alerting rules.
+- `dashboards/cogno_overview.json` — Grafana dashboard (import, pick your Prometheus datasource).
+- `dashboards/cogno_logs.json` — Grafana dashboard for live logs (Loki).
+- `prometheus-scrape.example.yml` — scrape config / ServiceMonitor example.
+- `SLOs.md` — starting SLOs + a metric→runbook map.
+
+## Deploy — one Grafana login for metrics + logs
+
+`deploy/` is a docker-compose stack (Prometheus + Loki + Promtail + Grafana) that watches an
+existing host and gives you **one Grafana login** to follow it live — metrics and near-real-time
+logs on the same pane. See [`deploy/README.md`](deploy/README.md).
+
+## Host integration
+
+The host exposes two seams (`metrics_sink=` + `instrument(app)`) and stays prometheus-agnostic;
+this library fills them. See [`docs/HOST_INTEGRATION.md`](docs/HOST_INTEGRATION.md).
+
+## The Cogno ecosystem
+
+`cogno-observability` is one organ of **[Cogno](https://github.com/sudoers-ai)** — a family of
+small, composable, Apache-2.0 libraries that together form a complete conversational-agent
+platform. Each library owns a single concern and stays infra-agnostic; a **host** assembles them
+into a running agent:
+
+![The Cogno ecosystem](docs/assets/cogno-ecosystem.svg)
+
+The open-source libraries are the organs; the **host is the body** that joins them. Our reference
+host — `cogno-host`, with its `cogno-ui` dashboard — is the private product layer, but it holds no
+special powers: everything it does rides on the public seams documented in each library's
+`docs/HOST_INTEGRATION.md`.

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

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+cogno_observability/__init__.py
+cogno_observability/instrument.py
+cogno_observability/metrics.py
+cogno_observability/sink.py
+cogno_observability.egg-info/PKG-INFO
+cogno_observability.egg-info/SOURCES.txt
+cogno_observability.egg-info/dependency_links.txt
+cogno_observability.egg-info/requires.txt
+cogno_observability.egg-info/top_level.txt
+tests/test_contract.py
+tests/test_instrument.py
+tests/test_sink.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,14 @@
+prometheus-client>=0.20
+
+[dev]
+pytest>=8
+pytest-asyncio>=0.23
+pytest-cov>=5.0
+prometheus-fastapi-instrumentator>=7.0
+fastapi>=0.110
+httpx>=0.27
+ruff>=0.5
+mypy>=1.8
+
+[http]
+prometheus-fastapi-instrumentator>=7.0

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

@@ -0,0 +1 @@
+cogno_observability

cogno_observability-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cogno-observability"
+version = "0.1.0"
+description = "SRE/Ops monitoring for the Cogno stack — Prometheus metrics sink + /metrics wiring + Grafana dashboards/alerts. Cross-tenant fleet health (NOT the tenant-facing Radar Tokens; NOT billing)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Vinicius Vale" }]
+maintainers = [{ name = "Sudoers AI" }]
+dependencies = [
+    "prometheus-client>=0.20",
+]
+
+[project.optional-dependencies]
+# The FastAPI HTTP-layer instrumentation (RED metrics per route) is optional: the business
+# metrics (per-turn TurnEvent) work without it.
+http = ["prometheus-fastapi-instrumentator>=7.0"]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "prometheus-fastapi-instrumentator>=7.0",
+    "fastapi>=0.110",
+    "httpx>=0.27",
+    "ruff>=0.5",
+    "mypy>=1.8",
+]
+
+[tool.setuptools.packages.find]
+include = ["cogno_observability*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+files = ["cogno_observability"]
+warn_unused_ignores = true

cogno_observability-0.1.0/setup.cfg

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

cogno_observability-0.1.0/tests/test_contract.py

@@ -0,0 +1,51 @@
+"""Cross-repo contract: the host's real ``TurnEvent`` drives ``PrometheusMetricsSink``.
+
+The sink duck-types the event, so a silent field rename on the host would degrade a metric to 0
+with no failing test. This test closes that gap by importing the **real** ``cogno_host.TurnEvent``
+and asserting (a) it satisfies the ``TurnEventLike`` shape the sink relies on, and (b) a real event
+actually populates the series end-to-end. Auto-skips if cogno-host isn't installed (this repo stays
+standalone)."""
+
+from __future__ import annotations
+
+import pytest
+from prometheus_client import CollectorRegistry
+
+from cogno_observability import PrometheusMetricsSink
+from cogno_observability.sink import TurnEventLike
+
+cogno_host = pytest.importorskip("cogno_host", reason="cogno-host not installed")
+
+
+def test_real_turnevent_satisfies_sink_shape():
+    # runtime_checkable Protocol → isinstance verifies every attribute the sink reads exists.
+    e = cogno_host.TurnEvent(tenant_id="acme", session_id="s1")
+    assert isinstance(e, TurnEventLike)
+
+
+def test_real_turnevent_drives_the_series_end_to_end():
+    reg = CollectorRegistry()
+    sink = PrometheusMetricsSink(registry=reg)
+    e = cogno_host.TurnEvent(
+        tenant_id="acme", session_id="s1", route="EGO", stop_reason="completed",
+        total_tokens=15, elapsed_ms=1200.0, cost_usd=0.002, drift_cumulative=0.3,
+        drift_action="warn", tool_calls=1, handoff=False,
+        stages=[cogno_host.StageSample(stage="ner", model="mistral",
+                                       tokens_in=10, tokens_out=5, elapsed_ms=200.0)])
+    sink.record(e)
+
+    assert reg.get_sample_value("cogno_turns_total", {
+        "route": "EGO", "stop_reason": "completed", "ok": "true",
+        "blocked": "false", "cache_hit": "false"}) == 1.0
+    assert reg.get_sample_value("cogno_stage_tokens_total",
+                                {"stage": "ner", "model": "mistral", "direction": "in"}) == 10.0
+    assert reg.get_sample_value("cogno_drift_actions_total", {"action": "warn"}) == 1.0
+    assert reg.get_sample_value("cogno_turn_duration_seconds_count", {"route": "EGO"}) == 1.0
+
+
+def test_sink_reads_every_field_the_host_provides():
+    # Belt-and-suspenders: every attribute named in TurnEventLike is present on the host DTO, so
+    # the getattr defaults in the sink are a safety net, never the actual data path.
+    e = cogno_host.TurnEvent(tenant_id="acme", session_id="s1")
+    for field in TurnEventLike.__annotations__:
+        assert hasattr(e, field), f"host TurnEvent is missing '{field}' the sink reads"

cogno_observability-0.1.0/tests/test_instrument.py

@@ -0,0 +1,43 @@
+"""attach(app) mounts a working /metrics endpoint and instruments HTTP routes."""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from cogno_observability import PrometheusMetricsSink, attach
+
+
+def _app() -> FastAPI:
+    app = FastAPI()
+    attach(app)                       # mounts /metrics + HTTP instrumentation (before routes)
+
+    @app.get("/ping")
+    def ping() -> dict:
+        return {"ok": True}
+
+    return app
+
+
+def test_metrics_endpoint_exposes_series():
+    app = _app()
+    # record a business metric onto the global registry the endpoint scrapes
+    from types import SimpleNamespace
+    PrometheusMetricsSink().record(SimpleNamespace(
+        route="EGO", stop_reason="completed", ok=True, blocked=False, cache_hit=False,
+        elapsed_ms=500, stages=[], cost_usd=0.0, drift_cumulative=0.0, drift_action="",
+        tool_calls=0, tool_failures=0, failover_count=0, correction_count=0, handoff=False,
+        error="", tenant_id="acme", total_tokens=0))
+    client = TestClient(app)
+    client.get("/ping")               # generate an HTTP-layer sample
+    body = client.get("/metrics").text
+    assert "cogno_turns_total" in body                 # business metric
+    assert "http_request" in body or "http_requests" in body   # HTTP RED (instrumentator)
+
+
+def test_metrics_endpoint_ok_without_http_extra():
+    # instrument_http=False must still serve /metrics (business metrics only)
+    app = FastAPI()
+    attach(app, instrument_http=False)
+    body = TestClient(app).get("/metrics").text
+    assert "python_info" in body or "cogno_" in body   # a valid exposition page

cogno_observability-0.1.0/tests/test_sink.py

@@ -0,0 +1,146 @@
+"""Unit tests for PrometheusMetricsSink — TurnEvent → Prometheus series (fresh registry each)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import pytest
+from prometheus_client import CollectorRegistry
+
+from cogno_observability import PrometheusMetricsSink
+
+
+# ── minimal stand-ins for the host's TurnEvent / StageSample (duck-typed, no cogno_host dep) ──
+@dataclass
+class Stage:
+    stage: str
+    model: str = "fake"
+    tokens_in: int = 0
+    tokens_out: int = 0
+    embedding_tokens: int = 0
+    elapsed_ms: float = 0.0
+
+
+@dataclass
+class Event:
+    tenant_id: str = "acme"
+    route: str = "EGO"
+    stop_reason: str = "completed"
+    total_tokens: int = 0
+    elapsed_ms: float = 0.0
+    cache_hit: bool = False
+    blocked: bool = False
+    ok: bool = True
+    error: str = ""
+    cost_usd: float = 0.0
+    drift_cumulative: float = 0.0
+    drift_action: str = ""
+    tool_calls: int = 0
+    tool_failures: int = 0
+    failover_count: int = 0
+    correction_count: int = 0
+    handoff: bool = False
+    grounding_rule: str = ""
+    grounding_repaired: bool = False
+    provenance_refusals: int = 0
+    stages: list = field(default_factory=list)
+
+
+@pytest.fixture
+def reg():
+    return CollectorRegistry()
+
+
+def test_turn_counter_and_latency(reg):
+    sink = PrometheusMetricsSink(registry=reg)
+    sink.record(Event(route="EGO", stop_reason="completed", elapsed_ms=1500))
+    v = reg.get_sample_value("cogno_turns_total", {
+        "route": "EGO", "stop_reason": "completed", "ok": "true",
+        "blocked": "false", "cache_hit": "false"})
+    assert v == 1.0
+    assert reg.get_sample_value("cogno_turn_duration_seconds_count", {"route": "EGO"}) == 1.0
+
+
+def test_failed_turn_increments_errors(reg):
+    sink = PrometheusMetricsSink(registry=reg)
+    sink.record(Event(ok=False, error="MCPDispatchError", stop_reason="error"))
+    assert reg.get_sample_value("cogno_turn_errors_total", {"error": "MCPDispatchError"}) == 1.0
+
+
+def test_stage_tokens_by_model_and_direction(reg):
+    sink = PrometheusMetricsSink(registry=reg)
+    sink.record(Event(stages=[
+        Stage("ner", model="mistral", tokens_in=100, tokens_out=40, elapsed_ms=200),
+        Stage("id", model="heuristic", embedding_tokens=12),
+    ]))
+    assert reg.get_sample_value("cogno_stage_tokens_total",
+                                {"stage": "ner", "model": "mistral", "direction": "in"}) == 100.0
+    assert reg.get_sample_value("cogno_stage_tokens_total",
+                                {"stage": "ner", "model": "mistral", "direction": "out"}) == 40.0
+    assert reg.get_sample_value("cogno_stage_tokens_total",
+                                {"stage": "id", "model": "heuristic",
+                                 "direction": "embedding"}) == 12.0
+    assert reg.get_sample_value("cogno_stage_duration_seconds_count", {"stage": "ner"}) == 1.0
+
+
+def test_cost_drift_tools_reliability(reg):
+    sink = PrometheusMetricsSink(registry=reg)
+    sink.record(Event(cost_usd=0.0123, drift_cumulative=0.42, drift_action="warn",
+                      tool_calls=3, tool_failures=1, failover_count=2,
+                      correction_count=1, handoff=True))
+    assert reg.get_sample_value("cogno_cost_usd_total") == pytest.approx(0.0123)
+    assert reg.get_sample_value("cogno_drift_actions_total", {"action": "warn"}) == 1.0
+    assert reg.get_sample_value("cogno_drift_score_count") == 1.0
+    assert reg.get_sample_value("cogno_tool_calls_total") == 3.0
+    assert reg.get_sample_value("cogno_tool_failures_total") == 1.0
+    assert reg.get_sample_value("cogno_failovers_total") == 2.0
+    assert reg.get_sample_value("cogno_self_corrections_total") == 1.0
+    assert reg.get_sample_value("cogno_handoffs_total") == 1.0
+
+
+def test_blocked_turn_counted(reg):
+    sink = PrometheusMetricsSink(registry=reg)
+    sink.record(Event(blocked=True, stop_reason="quota_exceeded"))
+    assert reg.get_sample_value("cogno_blocked_total", {"stop_reason": "quota_exceeded"}) == 1.0
+
+
+def test_record_never_raises_on_garbage(reg):
+    sink = PrometheusMetricsSink(registry=reg)
+    sink.record(object())            # missing every attribute → swallowed, no exception
+
+
+def test_tenant_label_opt_in(reg):
+    sink = PrometheusMetricsSink(registry=reg, tenant_label=True)
+    sink.record(Event(tenant_id="acme"))
+    assert reg.get_sample_value("cogno_turns_by_tenant_total",
+                                {"tenant": "acme", "ok": "true"}) == 1.0
+
+
+def test_two_sinks_on_same_registry_share_series(reg):
+    # A second sink on the same registry must not crash (Duplicated timeseries) — it reuses the
+    # existing collectors, so counts from both accumulate onto one series.
+    s1 = PrometheusMetricsSink(registry=reg)
+    s2 = PrometheusMetricsSink(registry=reg)          # must NOT raise
+    s1.record(Event(route="EGO", stop_reason="completed"))
+    s2.record(Event(route="EGO", stop_reason="completed"))
+    assert reg.get_sample_value("cogno_turns_total", {
+        "route": "EGO", "stop_reason": "completed", "ok": "true",
+        "blocked": "false", "cache_hit": "false"}) == 2.0
+
+
+def test_two_default_registry_sinks_do_not_crash():
+    # The real-world footgun: PrometheusMetricsSink() twice on the global REGISTRY.
+    PrometheusMetricsSink()
+    PrometheusMetricsSink()                            # must NOT raise
+
+
+def test_protection_net_counters(reg):
+    # grounding rewrite (rule + repaired) and provenance refusals land as counters; a clean
+    # turn (empty rule, zero refusals) emits neither series.
+    sink = PrometheusMetricsSink(registry=reg)
+    sink.record(Event(grounding_rule="performative_without_commit", grounding_repaired=True,
+                      provenance_refusals=2))
+    sink.record(Event())                                     # clean turn → no net samples
+    assert reg.get_sample_value("cogno_grounding_rewrites_total", {
+        "rule": "performative_without_commit", "repaired": "true"}) == 1.0
+    assert reg.get_sample_value("cogno_provenance_refusals_total") == 2.0