nucleus-core-ts 0.10.147 → 0.10.151

package/public/components/docs/content/monitoring.ts

@@ -1,313 +1,313 @@
-import type { DocItem } from '../docsData'
-
-export const monitoringItems: DocItem[] = [
-  {
-    id: 'monitoring-system',
-    title: 'Monitoring System',
-    subItems: [
-      {
-        id: 'monitoring-overview',
-        title: 'Monitoring Overview',
-        content: `
-## Monitoring Overview
-
-Nucleus includes two monitoring systems: **Application Monitoring** (request metrics, error tracking, alerts) and **Live Monitoring** (real-time memory/CPU/request streaming via SSE).
-
-### Application Monitoring
-
-Tracks request-level metrics across your API:
-
-| Metric Category | What It Tracks |
-|----------------|----------------|
-| **Requests** | Total count, per-endpoint breakdown, method distribution |
-| **Response Time** | Average, p50, p95, p99 latencies |
-| **Errors** | Error count, error rate, status code distribution |
-| **Rate Limits** | Blocked requests, rate limit hits per endpoint |
-
-### System Monitoring
-
-Tracks server-level resource usage:
-
-| Metric | Description |
-|--------|-------------|
-| **CPU** | Usage percentage, load average |
-| **Memory** | RSS, heap used/total, external, array buffers |
-| **Disk** | Usage percentage (if enabled) |
-| **Network** | Connection count (if enabled) |
-| **Process** | Uptime, event loop lag |
-
-### Database Monitoring
-
-Collected from \`pg_stat_activity\` / \`pg_stat_database\`, scoped to the current database:
-
-| Metric | Description |
-|--------|-------------|
-| **Connections** | Active/idle/total backends |
-| **Query Time** | Avg active execution time per transaction (PostgreSQL 14+) |
-| **Slow Queries** | Currently active queries exceeding \`slowQueryThreshold\` |
-
-### Redis Monitoring
-
-Collected via the Redis \`INFO\` command (direct Redis mode only — unavailable when \`redis.withDapr\` is true):
-
-| Metric | Description |
-|--------|-------------|
-| **Memory** | Used / peak memory |
-| **Connections** | Connected clients |
-| **Operations** | Total commands, instantaneous ops/sec |
-| **Hit Rate** | Keyspace hits vs misses (%) |
-
-### Alert System
-
-When metrics exceed configured thresholds, alerts are triggered:
-
-\`\`\`json
-{
-  "monitoring": {
-    "alerts": {
-      "enabled": true,
-      "email": {
-        "enabled": true,
-        "recipients": ["ops@yourapp.com"]
-      },
-      "thresholds": {
-        "cpuPercent": 90,
-        "memoryPercent": 85,
-        "diskPercent": 90,
-        "errorRatePercent": 5,
-        "responseTimeMs": 2000,
-        "rateLimitBlocksPerMinute": 100
-      },
-      "cooldown": "5m"
-    }
-  }
-}
-\`\`\`
-
-The \`cooldown\` prevents alert spam — after an alert fires, the same alert won't fire again for the cooldown duration.
-        `,
-      },
-      {
-        id: 'monitoring-config',
-        title: 'Full Configuration',
-        content: `
-## Monitoring Configuration
-
-\`\`\`json
-{
-  "monitoring": {
-    "enabled": true,
-    "system": {
-      "enabled": true,
-      "collectInterval": "10s",
-      "metrics": {
-        "cpu": true,
-        "memory": true,
-        "disk": true,
-        "network": true,
-        "process": true
-      }
-    },
-    "application": {
-      "enabled": true,
-      "metrics": {
-        "requests": true,
-        "responseTime": true,
-        "errors": true,
-        "rateLimits": true
-      }
-    },
-    "database": {
-      "enabled": true,
-      "metrics": {
-        "connections": true,
-        "queryTime": true,
-        "slowQueryThreshold": "500ms"
-      }
-    },
-    "redis": {
-      "enabled": true
-    },
-    "persistence": {
-      "enabled": true,
-      "flushInterval": "60s",
-      "retentionDays": 7
-    },
-    "endpoints": {
-      "enabled": true,
-      "basePath": "/monitoring",
-      "stream": {
-        "enabled": true,
-        "path": "/stream",
-        "interval": "5s"
-      },
-      "snapshot": {
-        "enabled": true,
-        "path": "/snapshot"
-      },
-      "history": {
-        "enabled": true,
-        "path": "/history",
-        "maxMinutes": 60
-      },
-      "alerts": {
-        "enabled": true,
-        "path": "/alerts"
-      }
-    }
-  }
-}
-\`\`\`
-
-### Monitoring Endpoints
-
-| Endpoint | Description |
-|----------|-------------|
-| \`GET /monitoring/snapshot\` | Current metrics snapshot |
-| \`GET /monitoring/stream\` | SSE stream of metric updates |
-| \`GET /monitoring/history?minutes=30\` | Historical metrics |
-| \`GET /monitoring/alerts\` | Recent alert history |
-
-### Persistence
-
-When \`persistence.enabled\` is on (default), collected metric points are flushed to the \`monitoring_metrics\` system table every \`flushInterval\` and rows older than \`retentionDays\` are pruned daily. The table is part of the generated schema only when monitoring is enabled — re-run \`nucleus-generate\` after enabling monitoring.
-        `,
-      },
-    ],
-  },
-  {
-    id: 'live-monitoring',
-    title: 'Live Monitoring',
-    subItems: [
-      {
-        id: 'live-monitoring-overview',
-        title: 'Live Monitoring (SSE)',
-        content: `
-## Live Monitoring — Real-Time SSE Stream
-
-Live Monitoring provides an in-memory, real-time monitoring service that streams server health data via Server-Sent Events (SSE). It's designed for admin dashboards that need live visibility into server state.
-
-### What It Tracks
-
-| Category | Data |
-|----------|------|
-| **Memory** | RSS, heap used/total, external, array buffers — sampled at configurable intervals |
-| **CPU** | Usage percentage — sampled at configurable intervals |
-| **Requests** | Every HTTP request: method, path, status, duration, user ID, IP |
-| **Dapr Events** | Dapr sidecar interactions (if Dapr is enabled) |
-| **WebSocket** | WS connection events and message counts |
-
-All data is stored in circular buffers with configurable limits — no database, no persistence. This keeps it zero-cost for production.
-
-### SSE Stream
-
-\`\`\`
-GET /live-monitoring/logs/stream
-\`\`\`
-
-The stream sends two event types:
-
-**snapshot** — Sent once on connection. Contains all current buffered data (memory logs, CPU logs, recent requests, Dapr events, WS events, worker info).
-
-**update** — Sent at \`streamInterval\` (default: 2s). Contains only new data since the last update.
-
-### Other Endpoints
-
-| Endpoint | Description |
-|----------|-------------|
-| \`GET /live-monitoring/health\` | Service health check |
-| \`GET /live-monitoring/settings\` | Current monitoring settings |
-| \`PATCH /live-monitoring/settings\` | Update settings at runtime |
-| \`GET /live-monitoring/logs\` | One-shot snapshot of all buffered data |
-
-### Runtime Settings
-
-You can toggle monitoring features and adjust intervals without restarting:
-
-\`\`\`bash
-PATCH /live-monitoring/settings
-Content-Type: application/json
-
-{
-  "logMemory": true,
-  "logCpu": true,
-  "memoryLogInterval": 5000,
-  "cpuLogInterval": 5000,
-  "memoryLogLimit": 100,
-  "requestLogLimit": 200
-}
-\`\`\`
-
-### Configuration
-
-\`\`\`json
-{
-  "liveMonitoring": {
-    "enabled": true,
-    "logMemory": true,
-    "logCpu": true,
-    "logDapr": false,
-    "logWebSocket": false,
-    "memoryLogInterval": 5000,
-    "cpuLogInterval": 5000,
-    "memoryLogLimit": 100,
-    "cpuLogLimit": 100,
-    "daprLogLimit": 50,
-    "wsLogLimit": 50,
-    "requestLogLimit": 200,
-    "streamInterval": 2000,
-    "basePath": "/live-monitoring"
-  }
-}
-\`\`\`
-        `,
-      },
-      {
-        id: 'health-endpoint',
-        title: 'Health Checks',
-        content: `
-## Health Checks
-
-Nucleus automatically creates a health check endpoint:
-
-\`\`\`
-GET /health
-\`\`\`
-
-### Response
-
-\`\`\`json
-{
-  "status": "ok",
-  "appId": "my-api",
-  "timestamp": "2024-01-15T10:30:00Z",
-  "uptime": 86400
-}
-\`\`\`
-
-This endpoint is always public (no authentication required) and is used by:
-- **Kubernetes liveness/readiness probes**
-- **Load balancer health checks**
-- **External monitoring services**
-
-### Kubernetes Probe Example
-
-\`\`\`yaml
-livenessProbe:
-  httpGet:
-    path: /health
-    port: 9000
-  initialDelaySeconds: 30
-  periodSeconds: 10
-readinessProbe:
-  httpGet:
-    path: /health
-    port: 9000
-  initialDelaySeconds: 5
-  periodSeconds: 5
-\`\`\`
-        `,
-      },
-    ],
-  },
-]
+import type { DocItem } from '../docsData'
+
+export const monitoringItems: DocItem[] = [
+  {
+    id: 'monitoring-system',
+    title: 'Monitoring System',
+    subItems: [
+      {
+        id: 'monitoring-overview',
+        title: 'Monitoring Overview',
+        content: `
+## Monitoring Overview
+
+Nucleus includes two monitoring systems: **Application Monitoring** (request metrics, error tracking, alerts) and **Live Monitoring** (real-time memory/CPU/request streaming via SSE).
+
+### Application Monitoring
+
+Tracks request-level metrics across your API:
+
+| Metric Category | What It Tracks |
+|----------------|----------------|
+| **Requests** | Total count, per-endpoint breakdown, method distribution |
+| **Response Time** | Average, p50, p95, p99 latencies |
+| **Errors** | Error count, error rate, status code distribution |
+| **Rate Limits** | Blocked requests, rate limit hits per endpoint |
+
+### System Monitoring
+
+Tracks server-level resource usage:
+
+| Metric | Description |
+|--------|-------------|
+| **CPU** | Usage percentage, load average |
+| **Memory** | RSS, heap used/total, external, array buffers |
+| **Disk** | Usage percentage (if enabled) |
+| **Network** | Connection count (if enabled) |
+| **Process** | Uptime, event loop lag |
+
+### Database Monitoring
+
+Collected from \`pg_stat_activity\` / \`pg_stat_database\`, scoped to the current database:
+
+| Metric | Description |
+|--------|-------------|
+| **Connections** | Active/idle/total backends |
+| **Query Time** | Avg active execution time per transaction (PostgreSQL 14+) |
+| **Slow Queries** | Currently active queries exceeding \`slowQueryThreshold\` |
+
+### Redis Monitoring
+
+Collected via the Redis \`INFO\` command (direct Redis mode only — unavailable when \`redis.withDapr\` is true):
+
+| Metric | Description |
+|--------|-------------|
+| **Memory** | Used / peak memory |
+| **Connections** | Connected clients |
+| **Operations** | Total commands, instantaneous ops/sec |
+| **Hit Rate** | Keyspace hits vs misses (%) |
+
+### Alert System
+
+When metrics exceed configured thresholds, alerts are triggered:
+
+\`\`\`json
+{
+  "monitoring": {
+    "alerts": {
+      "enabled": true,
+      "email": {
+        "enabled": true,
+        "recipients": ["ops@yourapp.com"]
+      },
+      "thresholds": {
+        "cpuPercent": 90,
+        "memoryPercent": 85,
+        "diskPercent": 90,
+        "errorRatePercent": 5,
+        "responseTimeMs": 2000,
+        "rateLimitBlocksPerMinute": 100
+      },
+      "cooldown": "5m"
+    }
+  }
+}
+\`\`\`
+
+The \`cooldown\` prevents alert spam — after an alert fires, the same alert won't fire again for the cooldown duration.
+        `,
+      },
+      {
+        id: 'monitoring-config',
+        title: 'Full Configuration',
+        content: `
+## Monitoring Configuration
+
+\`\`\`json
+{
+  "monitoring": {
+    "enabled": true,
+    "system": {
+      "enabled": true,
+      "collectInterval": "10s",
+      "metrics": {
+        "cpu": true,
+        "memory": true,
+        "disk": true,
+        "network": true,
+        "process": true
+      }
+    },
+    "application": {
+      "enabled": true,
+      "metrics": {
+        "requests": true,
+        "responseTime": true,
+        "errors": true,
+        "rateLimits": true
+      }
+    },
+    "database": {
+      "enabled": true,
+      "metrics": {
+        "connections": true,
+        "queryTime": true,
+        "slowQueryThreshold": "500ms"
+      }
+    },
+    "redis": {
+      "enabled": true
+    },
+    "persistence": {
+      "enabled": true,
+      "flushInterval": "60s",
+      "retentionDays": 7
+    },
+    "endpoints": {
+      "enabled": true,
+      "basePath": "/monitoring",
+      "stream": {
+        "enabled": true,
+        "path": "/stream",
+        "interval": "5s"
+      },
+      "snapshot": {
+        "enabled": true,
+        "path": "/snapshot"
+      },
+      "history": {
+        "enabled": true,
+        "path": "/history",
+        "maxMinutes": 60
+      },
+      "alerts": {
+        "enabled": true,
+        "path": "/alerts"
+      }
+    }
+  }
+}
+\`\`\`
+
+### Monitoring Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| \`GET /monitoring/snapshot\` | Current metrics snapshot |
+| \`GET /monitoring/stream\` | SSE stream of metric updates |
+| \`GET /monitoring/history?minutes=30\` | Historical metrics |
+| \`GET /monitoring/alerts\` | Recent alert history |
+
+### Persistence
+
+When \`persistence.enabled\` is on (default), collected metric points are flushed to the \`monitoring_metrics\` system table every \`flushInterval\` and rows older than \`retentionDays\` are pruned daily. The table is part of the generated schema only when monitoring is enabled — re-run \`nucleus-generate\` after enabling monitoring.
+        `,
+      },
+    ],
+  },
+  {
+    id: 'live-monitoring',
+    title: 'Live Monitoring',
+    subItems: [
+      {
+        id: 'live-monitoring-overview',
+        title: 'Live Monitoring (SSE)',
+        content: `
+## Live Monitoring — Real-Time SSE Stream
+
+Live Monitoring provides an in-memory, real-time monitoring service that streams server health data via Server-Sent Events (SSE). It's designed for admin dashboards that need live visibility into server state.
+
+### What It Tracks
+
+| Category | Data |
+|----------|------|
+| **Memory** | RSS, heap used/total, external, array buffers — sampled at configurable intervals |
+| **CPU** | Usage percentage — sampled at configurable intervals |
+| **Requests** | Every HTTP request: method, path, status, duration, user ID, IP |
+| **Dapr Events** | Dapr sidecar interactions (if Dapr is enabled) |
+| **WebSocket** | WS connection events and message counts |
+
+All data is stored in circular buffers with configurable limits — no database, no persistence. This keeps it zero-cost for production.
+
+### SSE Stream
+
+\`\`\`
+GET /live-monitoring/logs/stream
+\`\`\`
+
+The stream sends two event types:
+
+**snapshot** — Sent once on connection. Contains all current buffered data (memory logs, CPU logs, recent requests, Dapr events, WS events, worker info).
+
+**update** — Sent at \`streamInterval\` (default: 2s). Contains only new data since the last update.
+
+### Other Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| \`GET /live-monitoring/health\` | Service health check |
+| \`GET /live-monitoring/settings\` | Current monitoring settings |
+| \`PATCH /live-monitoring/settings\` | Update settings at runtime |
+| \`GET /live-monitoring/logs\` | One-shot snapshot of all buffered data |
+
+### Runtime Settings
+
+You can toggle monitoring features and adjust intervals without restarting:
+
+\`\`\`bash
+PATCH /live-monitoring/settings
+Content-Type: application/json
+
+{
+  "logMemory": true,
+  "logCpu": true,
+  "memoryLogInterval": 5000,
+  "cpuLogInterval": 5000,
+  "memoryLogLimit": 100,
+  "requestLogLimit": 200
+}
+\`\`\`
+
+### Configuration
+
+\`\`\`json
+{
+  "liveMonitoring": {
+    "enabled": true,
+    "logMemory": true,
+    "logCpu": true,
+    "logDapr": false,
+    "logWebSocket": false,
+    "memoryLogInterval": 5000,
+    "cpuLogInterval": 5000,
+    "memoryLogLimit": 100,
+    "cpuLogLimit": 100,
+    "daprLogLimit": 50,
+    "wsLogLimit": 50,
+    "requestLogLimit": 200,
+    "streamInterval": 2000,
+    "basePath": "/live-monitoring"
+  }
+}
+\`\`\`
+        `,
+      },
+      {
+        id: 'health-endpoint',
+        title: 'Health Checks',
+        content: `
+## Health Checks
+
+Nucleus automatically creates a health check endpoint:
+
+\`\`\`
+GET /health
+\`\`\`
+
+### Response
+
+\`\`\`json
+{
+  "status": "ok",
+  "appId": "my-api",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "uptime": 86400
+}
+\`\`\`
+
+This endpoint is always public (no authentication required) and is used by:
+- **Kubernetes liveness/readiness probes**
+- **Load balancer health checks**
+- **External monitoring services**
+
+### Kubernetes Probe Example
+
+\`\`\`yaml
+livenessProbe:
+  httpGet:
+    path: /health
+    port: 9000
+  initialDelaySeconds: 30
+  periodSeconds: 10
+readinessProbe:
+  httpGet:
+    path: /health
+    port: 9000
+  initialDelaySeconds: 5
+  periodSeconds: 5
+\`\`\`
+        `,
+      },
+    ],
+  },
+]