feat(server): REST API over server_metrics for SaaS dashboards

Adds /api/v1/admin/server-metrics/{catalog,instances,query} so SaaS control
planes can build the server-health dashboard without direct ClickHouse
access. One generic /query endpoint covers every panel in the
server-self-metrics doc: aggregation (avg/sum/max/min/latest), group-by-tag,
filter-by-tag, counter-delta mode with per-server_instance_id rotation
handling, and a derived 'mean' statistic for timers. Regex-validated
identifiers, parameterised literals, 31-day range cap, 500-series response
cap. ADMIN-only via the existing /api/v1/admin/** RBAC gate. Docs updated:
all 17 suggested panels now expressed as single-endpoint queries.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

cameleer-server-core/src/main/java/com/cameleer/server/core/storage/ServerMetricsQueryStore.java

@@ -0,0 +1,36 @@
+package com.cameleer.server.core.storage;
+
+import com.cameleer.server.core.storage.model.ServerInstanceInfo;
+import com.cameleer.server.core.storage.model.ServerMetricCatalogEntry;
+import com.cameleer.server.core.storage.model.ServerMetricQueryRequest;
+import com.cameleer.server.core.storage.model.ServerMetricQueryResponse;
+
+import java.time.Instant;
+import java.util.List;
+
+/**
+ * Read-side access to the ClickHouse {@code server_metrics} table. Exposed
+ * to dashboards through {@code /api/v1/admin/server-metrics/**} so SaaS
+ * control planes don't need direct ClickHouse access.
+ */
+public interface ServerMetricsQueryStore {
+
+    /**
+     * Catalog of metric names observed in {@code [from, to)} along with their
+     * type, the set of statistics emitted, and the union of tag keys seen.
+     */
+    List<ServerMetricCatalogEntry> catalog(Instant from, Instant to);
+
+    /**
+     * Distinct {@code server_instance_id} values that wrote at least one
+     * sample in {@code [from, to)}, with first/last seen timestamps.
+     */
+    List<ServerInstanceInfo> listInstances(Instant from, Instant to);
+
+    /**
+     * Generic time-series query. See {@link ServerMetricQueryRequest} for
+     * request semantics. Implementations must enforce input validation and
+     * reject unsafe inputs with {@link IllegalArgumentException}.
+     */
+    ServerMetricQueryResponse query(ServerMetricQueryRequest request);
+}

cameleer-server-core/src/main/java/com/cameleer/server/core/storage/model/ServerInstanceInfo.java

@@ -0,0 +1,15 @@
+package com.cameleer.server.core.storage.model;
+
+import java.time.Instant;
+
+/**
+ * One row of the {@code /api/v1/admin/server-metrics/instances} response.
+ * Used by dashboards to partition counter-delta computations across server
+ * process boundaries (each boot rotates the id).
+ */
+public record ServerInstanceInfo(
+        String serverInstanceId,
+        Instant firstSeen,
+        Instant lastSeen
+) {
+}

cameleer-server-core/src/main/java/com/cameleer/server/core/storage/model/ServerMetricCatalogEntry.java

@@ -0,0 +1,17 @@
+package com.cameleer.server.core.storage.model;
+
+import java.util.List;
+
+/**
+ * One row of the {@code /api/v1/admin/server-metrics/catalog} response.
+ * Surfaces the set of statistics and tag keys observed for a metric across
+ * the requested window, so dashboards can build selectors without ClickHouse
+ * access.
+ */
+public record ServerMetricCatalogEntry(
+        String metricName,
+        String metricType,
+        List<String> statistics,
+        List<String> tagKeys
+) {
+}

cameleer-server-core/src/main/java/com/cameleer/server/core/storage/model/ServerMetricPoint.java

@@ -0,0 +1,10 @@
+package com.cameleer.server.core.storage.model;
+
+import java.time.Instant;
+
+/** One {@code (bucket, value)} point of a server-metrics series. */
+public record ServerMetricPoint(
+        Instant t,
+        double v
+) {
+}

cameleer-server-core/src/main/java/com/cameleer/server/core/storage/model/ServerMetricQueryRequest.java

@@ -0,0 +1,40 @@
+package com.cameleer.server.core.storage.model;
+
+import java.time.Instant;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Request contract for the generic server-metrics time-series query.
+ *
+ * <p>{@code aggregation} controls how multiple samples within a bucket
+ * collapse: {@code avg|sum|max|min|latest}. {@code mode} controls counter
+ * handling: {@code raw} returns values as stored (cumulative for counters),
+ * {@code delta} returns per-bucket positive-clipped differences computed
+ * per {@code server_instance_id}.
+ *
+ * <p>{@code statistic} filters which Micrometer sub-measurement to read
+ * ({@code value} / {@code count} / {@code total_time} / {@code total} /
+ * {@code max} / {@code mean}). {@code mean} is a derived statistic for
+ * timers: {@code sum(total_time|total) / sum(count)} per bucket.
+ *
+ * <p>{@code groupByTags} splits the output into one series per unique tag
+ * combination. {@code filterTags} narrows the input to samples whose tag
+ * map matches every entry.
+ *
+ * <p>{@code serverInstanceIds} is an optional allow-list. When null or
+ * empty all instances observed in the window are included.
+ */
+public record ServerMetricQueryRequest(
+        String metric,
+        String statistic,
+        Instant from,
+        Instant to,
+        Integer stepSeconds,
+        List<String> groupByTags,
+        Map<String, String> filterTags,
+        String aggregation,
+        String mode,
+        List<String> serverInstanceIds
+) {
+}

cameleer-server-core/src/main/java/com/cameleer/server/core/storage/model/ServerMetricQueryResponse.java

@@ -0,0 +1,14 @@
+package com.cameleer.server.core.storage.model;
+
+import java.util.List;
+
+/** Response of the generic server-metrics time-series query. */
+public record ServerMetricQueryResponse(
+        String metric,
+        String statistic,
+        String aggregation,
+        String mode,
+        int stepSeconds,
+        List<ServerMetricSeries> series
+) {
+}

cameleer-server-core/src/main/java/com/cameleer/server/core/storage/model/ServerMetricSeries.java

@@ -0,0 +1,14 @@
+package com.cameleer.server.core.storage.model;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * One series of the server-metrics query response, identified by its
+ * {@link #tags} group (empty map when the query had no {@code groupByTags}).
+ */
+public record ServerMetricSeries(
+        Map<String, String> tags,
+        List<ServerMetricPoint> points
+) {
+}