ragleap-observability 0.1.0__tar.gz

ragleap_observability-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Environment
+.env
+*.env.local
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+venv/
+.venv/
+
+# Node
+node_modules/
+
+# Docker
+docker-compose.override.yml
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+.env
+
+# Package build artifacts
+dist/
+build/

ragleap_observability-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to `ragleap-observability` are documented here. Format loosely
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+### Fixed
+
+- `postgres-exporter` had `runAsNonRoot: true` with no `runAsUser` set. The image's Dockerfile sets its user by name (`nobody`) rather than a numeric UID, which Kubernetes cannot verify against `runAsNonRoot` without an explicit numeric value -- failed on real cluster with `container has runAsNonRoot and image has non-numeric user (nobody), cannot verify user is non-root`. Fixed with `runAsUser: 65534`, confirmed via `docker run --rm --entrypoint id quay.io/prometheuscommunity/postgres-exporter:v0.15.0` (uid=65534(nobody)), not assumed. Distinct bug pattern from the earlier root-default-image issues found in `ragleap-ops` -- same root problem (runAsNonRoot needs a numeric UID) but a different underlying cause.
+
+### Added
+
+- Prometheus + `postgres_exporter`, step 1 of the planned build order (Prometheus/exporters first, alerting/dashboards later, per the README's own sequencing rationale -- alerting on data that doesn't exist yet is pointless).
+- `neo4jExporter` config present but disabled by default -- Neo4j Community Edition Prometheus support is unverified and conflicting across sources (Neo4j's own KB and a working xk6-neo4j example show it configured successfully against Community 4.4.x; a separate monitoring vendor's compatibility notes claim Community is unsupported for their specific collector). Documented in README "Known open items", stays disabled until independently live-verified.
+
+### Verified
+
+- `helm lint` clean; `helm template` output confirmed exactly 3 resources render (Deployment, Service, ConfigMap), and the `neo4jExporter` scrape job is correctly absent from the rendered Prometheus config since `neo4jExporter.enabled` defaults to false.
+- First live cluster deploy performed (`helm install` against a real kind cluster). `helm install` succeeded structurally with no template errors. The Prometheus ConfigMap deployed as a real object and its rendered content matched the earlier `helm template` output exactly -- only the `ragleap-postgres` scrape job present, `ragleap-neo4j` correctly absent, confirming `neo4jExporter.enabled: false` behaves identically on a real cluster, not just in template rendering. `postgres-exporter`'s pod failed exactly as pre-documented: `secret "ragleap-db-exporter-secret" not found` -- this is the already-known, already-flagged dependency gap (the read-only monitoring role does not yet exist in `ragleap-ops`'s db schema), not a new bug found by this test.
+
+### Verified (this session)
+
+- The `ragleap-ops` dependency is now resolved: `ragleap_monitor` role confirmed to genuinely exist in the live database via `psql -c "\\du ragleap_monitor"` (not assumed from the schema file alone), and `ragleap-db-exporter-secret` deployed successfully into the `ragleap-core` namespace.
+- After the `runAsUser: 65534` fix above, `postgres-exporter` reached `1/1 Running`, 0 restarts, on a real kind cluster.
+- Real end-to-end connectivity confirmed via `/metrics` endpoint (port-forwarded and curled directly, not just checked via pod status): `pg_up 1`, plus real non-zero live statistics for the `ragleap_core` database (`pg_stat_database_blks_hit`, `pg_stat_database_tup_returned`, `pg_stat_database_xact_commit`, `pg_stat_database_numbackends`, etc.) -- this is genuinely scraped data, not placeholder zeros. The exporter is proven to work end-to-end, not just "pod is green."
+
+### Known limitations
+
+- Neo4j Prometheus support genuinely unverified -- see Added section above. Do not enable `neo4jExporter` without independently confirming against the real `neo4j:5-community` image.
+- Grafana, Loki, and AlertManager are not yet built at all -- correctly sequenced after Prometheus has real metrics flowing, per the README's own build order.

ragleap_observability-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: ragleap-observability
+Version: 0.1.0
+Summary: Prometheus/Grafana/Loki/AlertManager observability stack for RagLeap Core, live-tested against a real cluster
+Project-URL: Homepage, https://packages.ragleap.com/docs/ragleap-observability.html
+Author: RagLeap Contributors
+License: MIT
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# ragleap-observability
+
+Metrics, logs, and alerting for RagLeap Core -- Prometheus, Grafana,
+Loki, and AlertManager, wired against the real db/app/voice/neo4j
+services.
+
+## Status
+
+Prometheus + `postgres_exporter` are built and live-verified end-to-end
+against a real cluster: the exporter connects to `ragleap-db` using a
+read-only monitoring role, and `/metrics` returns real, non-zero
+PostgreSQL statistics (`pg_up 1`, live `pg_stat_database` values). This
+is the prerequisite for AIOps per the project's own DevOps maturity
+roadmap -- building anomaly detection before a metrics pipeline exists
+would be "a dashboard for data that doesn't exist."
+
+Grafana, Loki, and AlertManager are not yet built -- correctly
+sequenced after Prometheus has proven real metrics flowing, per the
+build order below.
+
+## Planned build order
+
+1. ✅ Prometheus + exporters (postgres_exporter for db) -- done,
+   live-verified this session. neo4j's exporter remains disabled
+   pending independent verification, see "Known open items".
+2. Grafana, provisioned dashboards-as-code, verified against real
+   flowing data
+3. Loki + log shipping (can parallel step 2)
+4. AlertManager -- deliberately last; alerting on data that doesn't
+   exist yet is pointless
+5. SLO/SLI dashboards, only after real data has accumulated for days,
+   not minutes
+
+## Design principles
+
+- RagLeap-specific scoping, same honest choice `ragleap-ops` made for
+  itself -- not a generic monitoring tool
+- Every claim live-verified against a real cluster or explicitly
+  labeled unverified, same discipline as every other package here
+
+## Known open items
+
+- **Neo4j Prometheus support is unverified and conflicting in the wild.**
+  Neo4j's own KB and a working xk6-neo4j example show
+  `metrics.prometheus.enabled=true` configured successfully against
+  Neo4j Community 4.4.x. A separate monitoring vendor's own
+  compatibility notes claim Community Edition is unsupported for their
+  specific collector. `neo4jExporter.enabled` defaults to `false` in
+  `values.yaml` until this is live-verified against the real
+  `neo4j:5-community` image in this repo's own `kind` cluster.
+- ~~`ragleap-db`'s schema does not yet have a read-only monitoring role~~
+  **Resolved and live-verified this session.** The `ragleap_monitor`
+  role exists in `ragleap-ops`'s schema and `ragleap-db-exporter-secret`
+  connects successfully -- confirmed via real `/metrics` output showing
+  `pg_up 1` and live PostgreSQL statistics, not just a running pod.

ragleap_observability-0.1.0/README.md

@@ -0,0 +1,55 @@
+# ragleap-observability
+
+Metrics, logs, and alerting for RagLeap Core -- Prometheus, Grafana,
+Loki, and AlertManager, wired against the real db/app/voice/neo4j
+services.
+
+## Status
+
+Prometheus + `postgres_exporter` are built and live-verified end-to-end
+against a real cluster: the exporter connects to `ragleap-db` using a
+read-only monitoring role, and `/metrics` returns real, non-zero
+PostgreSQL statistics (`pg_up 1`, live `pg_stat_database` values). This
+is the prerequisite for AIOps per the project's own DevOps maturity
+roadmap -- building anomaly detection before a metrics pipeline exists
+would be "a dashboard for data that doesn't exist."
+
+Grafana, Loki, and AlertManager are not yet built -- correctly
+sequenced after Prometheus has proven real metrics flowing, per the
+build order below.
+
+## Planned build order
+
+1. ✅ Prometheus + exporters (postgres_exporter for db) -- done,
+   live-verified this session. neo4j's exporter remains disabled
+   pending independent verification, see "Known open items".
+2. Grafana, provisioned dashboards-as-code, verified against real
+   flowing data
+3. Loki + log shipping (can parallel step 2)
+4. AlertManager -- deliberately last; alerting on data that doesn't
+   exist yet is pointless
+5. SLO/SLI dashboards, only after real data has accumulated for days,
+   not minutes
+
+## Design principles
+
+- RagLeap-specific scoping, same honest choice `ragleap-ops` made for
+  itself -- not a generic monitoring tool
+- Every claim live-verified against a real cluster or explicitly
+  labeled unverified, same discipline as every other package here
+
+## Known open items
+
+- **Neo4j Prometheus support is unverified and conflicting in the wild.**
+  Neo4j's own KB and a working xk6-neo4j example show
+  `metrics.prometheus.enabled=true` configured successfully against
+  Neo4j Community 4.4.x. A separate monitoring vendor's own
+  compatibility notes claim Community Edition is unsupported for their
+  specific collector. `neo4jExporter.enabled` defaults to `false` in
+  `values.yaml` until this is live-verified against the real
+  `neo4j:5-community` image in this repo's own `kind` cluster.
+- ~~`ragleap-db`'s schema does not yet have a read-only monitoring role~~
+  **Resolved and live-verified this session.** The `ragleap_monitor`
+  role exists in `ragleap-ops`'s schema and `ragleap-db-exporter-secret`
+  connects successfully -- confirmed via real `/metrics` output showing
+  `pg_up 1` and live PostgreSQL statistics, not just a running pod.

ragleap_observability-0.1.0/helm/ragleap-observability/Chart.yaml

@@ -0,0 +1,6 @@
+apiVersion: v2
+name: ragleap-observability
+description: Prometheus/Grafana/Loki/AlertManager observability stack for RagLeap Core
+type: application
+version: 0.1.0
+appVersion: "0.1.0"

ragleap_observability-0.1.0/helm/ragleap-observability/templates/postgres-exporter-deployment.yaml

@@ -0,0 +1,33 @@
+{{- if .Values.postgresExporter.enabled }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: ragleap-postgres-exporter
+  labels:
+    app: ragleap-postgres-exporter
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: ragleap-postgres-exporter
+  template:
+    metadata:
+      labels:
+        app: ragleap-postgres-exporter
+    spec:
+      containers:
+        - name: postgres-exporter
+          image: {{ .Values.postgresExporter.image }}
+          ports:
+            - containerPort: {{ .Values.postgresExporter.port }}
+          env:
+            - name: DATA_SOURCE_NAME
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.postgresExporter.datasourceSecretName }}
+                  key: connection-string
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 65534
+            allowPrivilegeEscalation: false
+{{- end }}

ragleap_observability-0.1.0/helm/ragleap-observability/templates/postgres-exporter-service.yaml

@@ -0,0 +1,14 @@
+{{- if .Values.postgresExporter.enabled }}
+apiVersion: v1
+kind: Service
+metadata:
+  name: ragleap-postgres-exporter
+  labels:
+    app: ragleap-postgres-exporter
+spec:
+  selector:
+    app: ragleap-postgres-exporter
+  ports:
+    - port: {{ .Values.postgresExporter.port }}
+      targetPort: {{ .Values.postgresExporter.port }}
+{{- end }}

ragleap_observability-0.1.0/helm/ragleap-observability/templates/prometheus-configmap.yaml

@@ -0,0 +1,19 @@
+{{- if .Values.prometheus.enabled }}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: ragleap-prometheus-config
+data:
+  prometheus.yml: |
+    global:
+      scrape_interval: {{ .Values.prometheus.scrapeInterval }}
+    scrape_configs:
+      - job_name: 'ragleap-postgres'
+        static_configs:
+          - targets: ['ragleap-postgres-exporter:{{ .Values.postgresExporter.port }}']
+      {{- if .Values.neo4jExporter.enabled }}
+      - job_name: 'ragleap-neo4j'
+        static_configs:
+          - targets: ['ragleap-neo4j:{{ .Values.neo4jExporter.port }}']
+      {{- end }}
+{{- end }}

ragleap_observability-0.1.0/helm/ragleap-observability/values.yaml

@@ -0,0 +1,32 @@
+# ragleap-observability — Prometheus + exporters (step 1 of the planned build order)
+#
+# Grafana, Loki, and AlertManager are NOT yet configured here — per the
+# README's build order, alerting/dashboards come after real metrics
+# are proven flowing, not before.
+
+postgresExporter:
+  enabled: true
+  image: quay.io/prometheuscommunity/postgres-exporter:v0.15.0
+  # Connects to ragleap-db using a read-only monitoring role — NOT the
+  # app's own credentials. This role does not exist yet in ragleap-ops's
+  # db schema and needs to be created there first (real dependency,
+  # not yet done — see README "Known open items").
+  datasourceSecretName: ragleap-db-exporter-secret
+  port: 9187
+
+neo4jExporter:
+  # UNVERIFIED — see README "Known open items". Neo4j's own docs and a
+  # working xk6-neo4j example show `metrics.prometheus.enabled=true`
+  # configured successfully against Neo4j Community 4.4.x. A separate
+  # third-party monitoring vendor's compatibility notes claim Community
+  # Edition is unsupported for their specific collector. These sources
+  # conflict. Do not enable this until live-verified against the real
+  # neo4j:5-community image running in this repo's own kind cluster.
+  enabled: false
+  port: 2004
+
+prometheus:
+  enabled: true
+  image: prom/prometheus:v2.55.1
+  retention: 15d
+  scrapeInterval: 30s

ragleap_observability-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ragleap-observability"
+version = "0.1.0"
+description = "Prometheus/Grafana/Loki/AlertManager observability stack for RagLeap Core, live-tested against a real cluster"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "RagLeap Contributors" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://packages.ragleap.com/docs/ragleap-observability.html"
+
+[tool.hatchling.build.targets.wheel]
+packages = ["src/ragleap_observability"]

ragleap_observability-0.1.0/src/ragleap_observability/__init__.py

@@ -0,0 +1,19 @@
+"""ragleap-observability: metrics, logs, and alerting for RagLeap Core.
+
+This package ships Helm chart configuration wiring Prometheus (with
+exporters for db/neo4j), Grafana (provisioned dashboards-as-code),
+Loki (log aggregation), and AlertManager (routed to Slack/PagerDuty)
+against RagLeap Core's own 4 services -- same RagLeap-specific scoping
+choice ragleap-ops made for itself, not a generic tool.
+
+This is the prerequisite for AIOps per the DevOps maturity roadmap:
+anomaly detection and auto-remediation need a real metrics pipeline to
+operate on, which doesn't exist until this package ships.
+
+It contains almost no importable Python -- its purpose is to let the
+existing PyPI/git-tag release automation version and ship the helm/
+chart alongside this src/ tree, matching the release discipline of
+ragleap-ops, ragleap-rag, ragleap-graph, and ragleap-vectorstores.
+"""
+
+__version__ = "0.1.0"

ragleap_observability-0.1.0/tests/test_version.py

@@ -0,0 +1,5 @@
+import ragleap_observability
+
+
+def test_version_is_set():
+    assert ragleap_observability.__version__ == "0.1.0"