StellAIverse · OthmanImam · Jun 23, 2026 · Jun 22, 2026
diff --git a/docs/METRICS.md b/docs/METRICS.md
@@ -1,7 +1,121 @@
-### http_requests_total
-Counts all HTTP requests
+# Metrics & Prometheus Integration
 
-Labels:
-- method
-- route
-- status
+## Overview
+
+StellAIverse Backend exposes Prometheus-compatible metrics at `GET /metrics` (no auth required).
+
+## Endpoint
+
+```
+GET /metrics
+```
+
+Returns metrics in Prometheus text format (`text/plain; version=0.0.4`).
+
+## How It Works
+
+- `MetricsModule` registers a global `MetricsInterceptor` that automatically tracks every HTTP request.
+- `prom-client` collects Node.js default metrics (CPU, memory, event loop, GC) with the `stellaiverse_` prefix.
+- Custom metrics are defined in `src/config/metrics.ts` and exported for use across the codebase.
+
+## Available Metrics (≥ 20 custom metrics)
+
+### HTTP
+
+| Metric | Type | Labels |
+|--------|------|--------|
+| `stellaiverse_http_request_duration_seconds` | Histogram | `method`, `route`, `status_code` |
+| `stellaiverse_http_requests_total` | Counter | `method`, `route`, `status_code` |
+| `stellaiverse_http_requests_in_progress` | Gauge | `method`, `route` |
+| `stellaiverse_http_errors_total` | Counter | `method`, `route`, `status_code` |
+
+### Authentication
+
+| Metric | Type | Labels |
+|--------|------|--------|
+| `stellaiverse_auth_attempts_total` | Counter | `method` |
+| `stellaiverse_auth_success_total` | Counter | `method` |
+| `stellaiverse_auth_failures_total` | Counter | `method`, `reason` |
+| `stellaiverse_user_signups_total` | Counter | `method` |
+| `stellaiverse_active_users` | Gauge | — |
+
+### Database
+
+| Metric | Type | Labels |
+|--------|------|--------|
+| `stellaiverse_database_query_duration_seconds` | Histogram | `operation`, `table` |
+| `stellaiverse_active_connections` | Gauge | `type` |
+
+### Job Queue
+
+| Metric | Type | Labels |
+|--------|------|--------|
+| `stellaiverse_job_duration_seconds` | Histogram | `job_type`, `status` |
+| `stellaiverse_job_success_total` | Counter | `job_type` |
+| `stellaiverse_job_failure_total` | Counter | `job_type`, `failure_reason` |
+| `stellaiverse_queue_length` | Gauge | `queue_name`, `state` |
+
+### Application
+
+| Metric | Type | Labels |
+|--------|------|--------|
+| `stellaiverse_errors_total` | Counter | `type`, `severity` |
+
+### Node.js Default Metrics (via `collectDefaultMetrics`)
+
+All standard `prom-client` default metrics are collected with the `stellaiverse_` prefix, including:
+- `stellaiverse_nodejs_heap_size_used_bytes`
+- `stellaiverse_nodejs_heap_size_total_bytes`
+- `stellaiverse_nodejs_eventloop_lag_seconds`
+- `stellaiverse_nodejs_active_handles_total`
+- `stellaiverse_process_cpu_seconds_total`
+- and more...
+
+## Adding New Metrics
+
+1. Import the registry and create the metric in `src/config/metrics.ts`:
+
+```typescript
+import * as client from "prom-client";
+import { register } from "./metrics";
+
+export const myCounter = new client.Counter({
+  name: "stellaiverse_my_event_total",
+  help: "Total number of my events",
+  labelNames: ["label_a"],
+  registers: [register],
+});
+```
+
+2. Import and use it anywhere in the app:
+
+```typescript
+import { myCounter } from "../config/metrics";
+
+myCounter.inc({ label_a: "value" });
+```
+
+## Grafana Dashboard
+
+A pre-built Grafana dashboard template is available at:
+
+```
+docs/dashboards/stellaiverse-backend.json
+```
+
+Import it into Grafana:
+1. Navigate to **Dashboards → Import**
+2. Upload `stellaiverse-backend.json`
+3. Select your Prometheus datasource
+4. Click **Import**
+
+## Prometheus Scrape Config
+
+```yaml
+scrape_configs:
+  - job_name: stellaiverse-backend
+    static_configs:
+      - targets: ["localhost:3000"]
+    metrics_path: /metrics
+    scrape_interval: 15s
+```
diff --git a/docs/dashboards/stellaiverse-backend.json b/docs/dashboards/stellaiverse-backend.json
@@ -0,0 +1,263 @@
+{
+  "__inputs": [
+    {
+      "name": "DS_PROMETHEUS",
+      "label": "Prometheus",
+      "description": "",
+      "type": "datasource",
+      "pluginId": "prometheus",
+      "pluginName": "Prometheus"
+    }
+  ],
+  "__requires": [
+    { "type": "grafana", "id": "grafana", "name": "Grafana", "version": "9.0.0" },
+    { "type": "datasource", "id": "prometheus", "name": "Prometheus", "version": "1.0.0" },
+    { "type": "panel", "id": "timeseries", "name": "Time series", "version": "" },
+    { "type": "panel", "id": "stat", "name": "Stat", "version": "" },
+    { "type": "panel", "id": "gauge", "name": "Gauge", "version": "" }
+  ],
+  "annotations": { "list": [] },
+  "editable": true,
+  "fiscalYearStartMonth": 0,
+  "graphTooltip": 0,
+  "id": null,
+  "links": [],
+  "liveNow": false,
+  "panels": [
+    {
+      "collapsed": false,
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 0 },
+      "id": 100,
+      "title": "HTTP Traffic",
+      "type": "row"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": {
+        "defaults": {
+          "color": { "mode": "palette-classic" },
+          "unit": "reqps"
+        },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 1 },
+      "id": 1,
+      "options": { "tooltip": { "mode": "single", "sort": "none" } },
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+          "expr": "sum(rate(stellaiverse_http_requests_total[5m])) by (route, method)",
+          "legendFormat": "{{method}} {{route}}",
+          "refId": "A"
+        }
+      ],
+      "title": "Request Rate (req/s)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": {
+        "defaults": { "unit": "s", "color": { "mode": "palette-classic" } },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 1 },
+      "id": 2,
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+          "expr": "histogram_quantile(0.95, sum(rate(stellaiverse_http_request_duration_seconds_bucket[5m])) by (le, route))",
+          "legendFormat": "p95 {{route}}",
+          "refId": "A"
+        },
+        {
+          "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+          "expr": "histogram_quantile(0.50, sum(rate(stellaiverse_http_request_duration_seconds_bucket[5m])) by (le, route))",
+          "legendFormat": "p50 {{route}}",
+          "refId": "B"
+        }
+      ],
+      "title": "Request Latency (p50 / p95)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": {
+        "defaults": { "unit": "percentunit", "min": 0, "max": 1 },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 9 },
+      "id": 3,
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+          "expr": "sum(rate(stellaiverse_http_errors_total[5m])) / sum(rate(stellaiverse_http_requests_total[5m]))",
+          "legendFormat": "Error Rate",
+          "refId": "A"
+        }
+      ],
+      "title": "Error Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": {
+        "defaults": { "unit": "short" },
+        "overrides": []
+      },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 9 },
+      "id": 4,
+      "targets": [
+        {
+          "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+          "expr": "sum(stellaiverse_http_requests_in_progress) by (method)",
+          "legendFormat": "{{method}}",
+          "refId": "A"
+        }
+      ],
+      "title": "In-Progress Requests",
+      "type": "timeseries"
+    },
+    {
+      "collapsed": false,
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 17 },
+      "id": 101,
+      "title": "Authentication",
+      "type": "row"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": { "defaults": { "unit": "reqps" }, "overrides": [] },
+      "gridPos": { "h": 8, "w": 8, "x": 0, "y": 18 },
+      "id": 5,
+      "targets": [
+        {
+          "expr": "sum(rate(stellaiverse_auth_attempts_total[5m])) by (method)",
+          "legendFormat": "Attempts {{method}}"
+        },
+        {
+          "expr": "sum(rate(stellaiverse_auth_success_total[5m])) by (method)",
+          "legendFormat": "Success {{method}}"
+        },
+        {
+          "expr": "sum(rate(stellaiverse_auth_failures_total[5m])) by (method, reason)",
+          "legendFormat": "Failure {{method}} ({{reason}})"
+        }
+      ],
+      "title": "Auth Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": { "defaults": { "unit": "percentunit", "min": 0, "max": 1 }, "overrides": [] },
+      "gridPos": { "h": 8, "w": 8, "x": 8, "y": 18 },
+      "id": 6,
+      "targets": [
+        {
+          "expr": "sum(rate(stellaiverse_auth_success_total[5m])) / clamp_min(sum(rate(stellaiverse_auth_attempts_total[5m])), 1)",
+          "legendFormat": "Login Success Rate"
+        }
+      ],
+      "title": "Auth Success Rate",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": { "defaults": { "unit": "short" }, "overrides": [] },
+      "gridPos": { "h": 8, "w": 8, "x": 16, "y": 18 },
+      "id": 7,
+      "targets": [
+        {
+          "expr": "stellaiverse_active_users",
+          "legendFormat": "Active Users"
+        }
+      ],
+      "title": "Active Users",
+      "type": "stat"
+    },
+    {
+      "collapsed": false,
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 26 },
+      "id": 102,
+      "title": "Database",
+      "type": "row"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 27 },
+      "id": 8,
+      "targets": [
+        {
+          "expr": "histogram_quantile(0.95, sum(rate(stellaiverse_database_query_duration_seconds_bucket[5m])) by (le, operation, table))",
+          "legendFormat": "p95 {{operation}} {{table}}"
+        }
+      ],
+      "title": "DB Query Latency (p95)",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": { "defaults": { "unit": "short" }, "overrides": [] },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 27 },
+      "id": 9,
+      "targets": [
+        {
+          "expr": "stellaiverse_active_connections",
+          "legendFormat": "{{type}}"
+        }
+      ],
+      "title": "Active Connections",
+      "type": "timeseries"
+    },
+    {
+      "collapsed": false,
+      "gridPos": { "h": 1, "w": 24, "x": 0, "y": 35 },
+      "id": 103,
+      "title": "System Resources",
+      "type": "row"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": { "defaults": { "unit": "bytes" }, "overrides": [] },
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 36 },
+      "id": 10,
+      "targets": [
+        {
+          "expr": "stellaiverse_nodejs_heap_size_used_bytes",
+          "legendFormat": "Heap Used"
+        },
+        {
+          "expr": "stellaiverse_nodejs_heap_size_total_bytes",
+          "legendFormat": "Heap Total"
+        }
+      ],
+      "title": "Node.js Heap Memory",
+      "type": "timeseries"
+    },
+    {
+      "datasource": { "type": "prometheus", "uid": "${DS_PROMETHEUS}" },
+      "fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] },
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 36 },
+      "id": 11,
+      "targets": [
+        {
+          "expr": "stellaiverse_nodejs_eventloop_lag_seconds",
+          "legendFormat": "Event Loop Lag"
+        }
+      ],
+      "title": "Event Loop Lag",
+      "type": "timeseries"
+    }
+  ],
+  "refresh": "30s",
+  "schemaVersion": 38,
+  "style": "dark",
+  "tags": ["stellaiverse", "prometheus", "nodejs"],
+  "templating": { "list": [] },
+  "time": { "from": "now-1h", "to": "now" },
+  "timepicker": {},
+  "timezone": "browser",
+  "title": "StellAIverse Backend",
+  "uid": "stellaiverse-backend",
+  "version": 1
+}