feat: add /api/overview endpoint for public usage statistics

README.md

@@ -7,3 +7,50 @@ Client source code:
 
 Read more about how telemetry is collected from docs:
 - https://cozystack.io/docs/telemetry/
+
+## Public Statistics API
+
+The server exposes a `GET /api/overview` endpoint that returns aggregated usage statistics in JSON format. This data is used by the [Cozystack website](https://cozystack.io/) to display public telemetry on the [Telemetry page](https://cozystack.io/oss-health/telemetry/).
+
+### How it works
+
+1. On the **1st of each month at 00:01 Pacific Time**, the server queries VictoriaMetrics for the current state of all reporting clusters and stores a monthly snapshot to disk.
+2. On first startup (if no snapshot exists for the current month), an initial snapshot is collected automatically.
+3. The app list is fetched dynamically from [cozystack/cozystack packages/apps](https://github.com/cozystack/cozystack/tree/main/packages/apps) to ensure newly added applications are always included.
+4. The `/api/overview` endpoint aggregates stored snapshots into three time periods: **last month**, **last quarter** (3 months), and **last 12 months**.
+
+### Response format
+
+```json
+{
+  "generated_at": "2026-04-01T07:01:00Z",
+  "periods": {
+    "month": {
+      "label": "March 2026",
+      "start": "2026-03-01",
+      "end": "2026-03-31",
+      "clusters": 42,
+      "total_nodes": 210,
+      "avg_nodes_per_cluster": 5.0,
+      "total_tenants": 84,
+      "avg_tenants_per_cluster": 2.0,
+      "apps": {
+        "postgres": 120,
+        "redis": 85,
+        "kubernetes": 30
+      }
+    },
+    "quarter": { "..." : "averaged over 3 months" },
+    "year": { "..." : "averaged over 12 months" }
+  }
+}
+```
+
+### Configuration flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--forward-url` | `http://vminsert-cozy-telemetry:8480/insert/0/prometheus/api/v1/import/prometheus` | URL to forward ingested metrics to |
+| `--listen-addr` | `:8081` | Address to listen on |
+| `--vmselect-url` | `http://vmselect-cozy-telemetry:8481` | VictoriaMetrics vmselect base URL for queries |
+| `--snapshot-dir` | `/data/snapshots` | Directory to store monthly snapshot JSON files |

charts/cozy-telemetry/templates/deployment.yaml

@@ -21,10 +21,15 @@ spec:
         args:
           - "--forward-url={{ .Values.config.forwardURL }}"
           - "--listen-addr={{ .Values.config.listenAddr }}"
+          - "--vmselect-url={{ .Values.config.vmSelectURL }}"
+          - "--snapshot-dir={{ .Values.config.snapshotDir }}"
         ports:
         - containerPort: {{ .Values.service.port }}
         resources:
           {{- toYaml .Values.resources | nindent 10 }}
+        volumeMounts:
+        - name: snapshots
+          mountPath: {{ .Values.config.snapshotDir }}
         readinessProbe:
           tcpSocket:
             port: 8081
@@ -35,3 +40,6 @@ spec:
             port: 8081
           initialDelaySeconds: 15
           periodSeconds: 10
+      volumes:
+      - name: snapshots
+        emptyDir: {}

charts/cozy-telemetry/values.yaml

@@ -1,4 +1,4 @@
-replicaCount: 2
+replicaCount: 1
 
 image:
   repository: "ghcr.io/cozystack/cozystack-telemetry-server"
@@ -13,6 +13,8 @@ service:
 config:
   forwardURL: "http://vminsert-cozy-telemetry:8480/insert/0/prometheus/api/v1/import/prometheus"
   listenAddr: ":8081"
+  vmSelectURL: "http://vmselect-cozy-telemetry:8481"
+  snapshotDir: "/data/snapshots"
 
 resources:
   requests:

main.go

@@ -149,20 +149,34 @@ func main() {
 	// Define flags
 	forwardURL := flag.String("forward-url", "http://vminsert-cozy-telemetry:8480/insert/0/prometheus/api/v1/import/prometheus", "URL to forward the metrics to")
 	listenAddr := flag.String("listen-addr", ":8081", "Address to listen on for incoming metrics")
+	vmSelectURL := flag.String("vmselect-url", "http://vmselect-cozy-telemetry:8481", "VictoriaMetrics vmselect base URL for queries")
+	snapshotDir := flag.String("snapshot-dir", "/data/snapshots", "Directory to store monthly snapshots")
 	flag.Parse()
 
+	// Initialize overview manager
+	overview := NewOverviewManager(*vmSelectURL, *snapshotDir)
+
 	server := &http.Server{
 		Addr:         *listenAddr,
 		ReadTimeout:  10 * time.Second,
 		WriteTimeout: 10 * time.Second,
 	}
 
+	// The overview handler may query VictoriaMetrics on cache miss (up to 30s),
+	// so it gets its own 55s timeout instead of inheriting the global 10s WriteTimeout.
+	http.Handle("/api/overview", http.TimeoutHandler(
+		http.HandlerFunc(overview.HandleOverview),
+		55*time.Second,
+		`{"error":"request timeout"}`,
+	))
 	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
 		handleTelemetry(w, r, *forwardURL)
 	})
 
 	log.Printf("Starting server on %s", *listenAddr)
 	log.Printf("Forwarding metrics to %s", *forwardURL)
+	log.Printf("VictoriaMetrics select URL: %s", *vmSelectURL)
+	log.Printf("Snapshot directory: %s", *snapshotDir)
 
 	if err := server.ListenAndServe(); err != nil {
 		log.Fatalf("Server error: %v", err)