From 3c2409ed6ee7c041363102b5438e9b3b91da7918 Mon Sep 17 00:00:00 2001 From: hsiegeln <37154749+hsiegeln@users.noreply.github.com> Date: Fri, 24 Apr 2026 09:05:22 +0200 Subject: [PATCH] docs(server-metrics): document the built-in admin dashboard SERVER-CAPABILITIES.md now lists the two consumption paths (UI + REST API) side-by-side with visibility rules; the dashboard-builder doc leads with a "Built-in admin dashboard" section and a 2026-04-24 changelog entry so first-time readers know they don't have to build anything before seeing server health. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/SERVER-CAPABILITIES.md | 11 ++++++++++- docs/server-self-metrics.md | 14 +++++++++++++- 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/SERVER-CAPABILITIES.md b/docs/SERVER-CAPABILITIES.md index 2ccada24..d4f0e25d 100644 --- a/docs/SERVER-CAPABILITIES.md +++ b/docs/SERVER-CAPABILITIES.md @@ -208,7 +208,16 @@ All query endpoints require JWT with `VIEWER` role or higher. The server snapshots its own Micrometer registry into ClickHouse every 60 s (table `server_metrics`) — JVM, HTTP, DB pools, agent/ingestion business metrics, and alerting metrics. Use this instead of running an external Prometheus when building a server-health dashboard. The live scrape endpoint `/api/v1/prometheus` remains available for traditional scraping. -See [`docs/server-self-metrics.md`](./server-self-metrics.md) for the full metric catalog, suggested panels, and example queries. +Two ways to consume: + +| Consumer | How | +|---|---| +| Web UI (built-in) | `/admin/server-metrics` — 17 panels across Server Health / JVM / HTTP & DB / Alerting / Deployments with a 15 min–7 d time picker. ADMIN-only, hidden when `infrastructureendpoints=false`. | +| Programmatic | Generic REST API under `/api/v1/admin/server-metrics/{catalog,instances,query}`. Same visibility rules. Designed for SaaS control planes that embed server health in their own console. | + +Persistence can be disabled entirely with `cameleer.server.self-metrics.enabled=false`. Snapshot cadence via `cameleer.server.self-metrics.interval-ms` (default `60000`). + +See [`docs/server-self-metrics.md`](./server-self-metrics.md) for the full metric catalog, API contract, and ready-to-paste query bodies for each panel. --- diff --git a/docs/server-self-metrics.md b/docs/server-self-metrics.md index 742ef8cd..d84ec7bd 100644 --- a/docs/server-self-metrics.md +++ b/docs/server-self-metrics.md @@ -1,11 +1,22 @@ # Server Self-Metrics — Reference for Dashboard Builders -This is the reference for the SaaS team building the server-health dashboard. It documents the `server_metrics` ClickHouse table, every series you can expect to find in it, and the queries we recommend for each dashboard panel. +This is the reference for anyone building a server-health dashboard on top of the Cameleer server. It documents the `server_metrics` ClickHouse table, every series you can expect to find in it, and the queries we recommend for each dashboard panel. > **tl;dr** — Every 60 s, every meter in the server's Micrometer registry (all `cameleer.*`, all `alerting_*`, and the full Spring Boot Actuator set) is written into ClickHouse as one row per `(meter, statistic)` pair. No external Prometheus required. --- +## Built-in admin dashboard + +The server ships a ready-to-use dashboard at **`/admin/server-metrics`** in the web UI. It renders the 17 panels listed below using `ThemedChart` from the design system, with a time-range selector (15 min / 1 h / 6 h / 24 h / 7 d) and live auto-refresh. Visibility mirrors the Database and ClickHouse admin pages: + +- Requires the `ADMIN` role. +- Hidden when `cameleer.server.security.infrastructureendpoints=false` (both the backend endpoints and the sidebar entry disappear). + +Use this page for single-tenant installs and dev/staging — it's the fastest path to "is the server healthy right now?". For multi-tenant control planes, cross-environment rollups, or embedding metrics inside an existing operations console, call the REST API below instead. + +--- + ## Table schema ```sql @@ -507,3 +518,4 @@ Below are 17 panels, each expressed as a single `POST /api/v1/admin/server-metri - 2026-04-23 — initial write. Write-only backend. - 2026-04-23 — added generic REST API (`/api/v1/admin/server-metrics/{catalog,instances,query}`) so dashboards don't need direct ClickHouse access. All 17 suggested panels now expressed as single-endpoint queries. +- 2026-04-24 — shipped the built-in `/admin/server-metrics` UI dashboard. Gated by `infrastructureendpoints` + ADMIN, identical visibility to `/admin/{database,clickhouse}`. Source: `ui/src/pages/Admin/ServerMetricsAdminPage.tsx`.