docs: complete NaxOS architectural specs, migration guides, API reference, and CI workflows

2026-09-04 00:15:21 +02:00
parent 2719f87e9e
commit ce7c125391
11 changed files with 490 additions and 2 deletions
@@ -0,0 +1,16 @@
+# CNCF Perses Native Analytics Architecture
+
+## Why Perses over Standalone Grafana?
+
+Traditional NAS appliances that provide telemetry either bundle a heavy standalone Grafana instance (which requires its own SQLite/PostgreSQL database, user accounts, and separate session cookies) or write rudimentary, un-configurable charts into their dashboard.
+
+NaxOS takes a pioneering approach by integrating **Perses** (a Cloud Native Computing Foundation project):
+
+1. **GitOps & Declarative Native**:
+   - Perses dashboards and datasources are written in clean JSON/CUE manifests.
+   - Dashboards are checked into `/var/lib/perses/projects/naxos/dashboards` as code.
+2. **Embedded Direct Visualization**:
+   - The NaxOS Web Dashboard communicates with the internal Perses metrics API.
+   - Eliminates Grafana's multi-megabyte bundle overhead, auth barriers, and database schema migrations.
+3. **Optimized for OpenZFS Metrics**:
+   - Out-of-the-box panels monitor OpenZFS ARC hits, misses, ARC target sizing, IOPS, and disk latencies scraped from Prometheus and Node Exporter.