tilbudgivern/docs/ADVANCED_DASHBOARD_API.md

Advanced Dashboard - Health Monitoring API Guide

Overview

The Advanced Dashboard provides real-time monitoring of system health, including PM2 processes, database metrics, and API performance. All endpoints are located under /api/health/ and provide JSON responses.

Available Endpoints

1. PM2 Process Logs

Endpoint: GET /api/health/pm2-logs

Returns information about all PM2-managed processes.

Response Example:

{
  "success": true,
  "logs": [
    {
      "name": "tilbudgivern-unified",
      "pid": 12345,
      "status": "online",
      "cpu": "0.5",
      "memory": 256,
      "restarts": 2,
      "uptime": "2025-01-23T10:30:00Z"
    }
  ],
  "timestamp": "2025-01-23T14:30:00Z"
}

Fields:

• name: Process name
• pid: Process ID
• status: Current status (online, stopping, stopped, etc.)
• cpu: CPU usage percentage
• memory: Memory usage in MB
• restarts: Number of times the process has been restarted
• uptime: When the process started

Use Cases:

• Monitor process health
• Track memory and CPU usage
• Detect frequent restarts

---

2. SQL Database Status

Endpoint: GET /api/health/sql-status

Provides comprehensive database connection and metric information.

Response Example:

{
  "status": "ok",
  "timestamp": "2025-01-23T14:30:00Z",
  "message": "Database connected",
  "connected": true,
  "databaseSize": 52428800,
  "databaseSize_MB": 50,
  "tableCount": 25,
  "activeQueries": 3,
  "totalConnections": 5,
  "indexCount": 42,
  "poolStats": {
    "activeConnections": 2,
    "idleConnections": 3,
    "queueLength": 0
  }
}

Fields:

• status: Connection status (ok, warning, error, disconnected)
• connected: Boolean indicating connection status
• databaseSize: Total database size in bytes
• databaseSize_MB: Total database size in megabytes
• tableCount: Number of tables in the database
• activeQueries: Current number of active queries
• totalConnections: Total number of database connections
• indexCount: Total number of indexes
• poolStats: Connection pool statistics (if available)

Use Cases:

• Monitor database health
• Track database growth
• Monitor active queries and connections
• Detect connection pool issues

---

3. Detailed Health Check

Endpoint: GET /api/health/detailed

Comprehensive health status including database, memory, error rates, and recent errors.

Response Fields:

• status: Overall status (ok, degraded, error)
• uptime: Server uptime in seconds
• checks.database: Database connection latency
• checks.memory: Heap and system memory usage
• checks.errorRate: Request error rate for last hour
• checks.recentErrors: Last 5 errors from last hour

---

4. Quick Health Check

Endpoint: GET /api/health/quick

Fast health status for basic monitoring.

Response Fields:

• status: Overall status (ok, degraded, error)
• checks: Basic health indicators

---

5. System Logs

Endpoint: GET /api/health/logs

Retrieve system logs from the database.

Response:

{
  "success": true,
  "logs": [
    {
      "level": "ERROR",
      "context": "database",
      "message": "Connection timeout",
      "created_at": "2025-01-23T14:00:00Z"
    }
  ]
}

---

6. Performance Statistics

Endpoint: GET /api/health/stats

Get hourly performance statistics and top API endpoints.

Response Fields:

• hourlyStats: Array of hourly statistics (last 24 hours)
  • hour: Hour timestamp
  • requests: Number of requests
  • avg_response_time: Average response time in ms
  • errors: Number of errors (5xx status codes)
• topEndpoints: Top 10 API endpoints by hits
  • url: API endpoint
  • hits: Number of requests
  • avg_time: Average response time
  • errors: Number of errors

---

Using with Advanced Dashboard Component

The AdvancedDashboard React component automatically fetches data from these endpoints and displays them in a user-friendly interface.

Component Props

<AdvancedDashboard
  apiBaseUrl="http://localhost:4032"  // Optional, defaults to current origin
  project={{ project_name: "My Project" }}  // Optional project info
  onContinueToSmartPakke={() => {}}  // Optional callback
/>

Features

• Auto-refresh: Updates every 30 seconds
• Real-time metrics: CPU, memory, disk usage
• Process monitoring: PM2 processes with status
• Database metrics: Size, connections, queries
• API performance: Response time and uptime

Tabs

1. Overview - Summary of all systems
2. PM2 Processes - Detailed process grid
3. Database - Database metrics cards
4. API & Resources - API and server resource usage

---

Integration Example

Frontend Usage

import AdvancedDashboard from './components/AdvancedDashboard';

function AdminPage() {
  return (
    <AdvancedDashboard
      apiBaseUrl="/api"
      project={{ project_name: "Tilbudgivern" }}
    />
  );
}

Checking Health Programmatically

// Check PM2 processes
fetch('/api/health/pm2-logs')
  .then(r => r.json())
  .then(data => console.log('PM2 Processes:', data.logs));

// Check database status
fetch('/api/health/sql-status')
  .then(r => r.json())
  .then(data => console.log('DB Status:', data.status));

// Check detailed health
fetch('/api/health/detailed')
  .then(r => r.json())
  .then(data => console.log('Health:', data.status));

---

Error Handling

All endpoints gracefully handle errors:

• No database connection: Returns status: 'disconnected' with message
• PM2 not installed: Returns empty logs array with message
• SQL query failures: Returns error state but continues with other checks
• Timeout: Returns 5xx status with error message

---

Performance Notes

• PM2 Logs (~50-300ms): Depends on number of processes
• SQL Status (~100-500ms): May be slower if many queries are running
• Quick Check (~100-200ms): Fastest endpoint
• Detailed Check (~500-2000ms): Slowest, most comprehensive

---

Testing

Run the test suite:

npm run test:pw -- tests/advanced-dashboard.spec.js

Tests cover:

• Endpoint availability
• Response structure validation
• Data consistency
• Concurrent requests
• Response time validation

---

Troubleshooting

PM2 endpoint returns empty logs

• Check if PM2 is installed: npm list pm2
• Verify processes are running: pm2 list

SQL endpoint returns disconnected

• Check database connection in .env
• Verify database server is running
• Check connection pool status

High response times

• Check server CPU and memory usage
• Monitor active database queries
• Check network latency

Frequent restarts shown in PM2 logs

• Check application error logs
• Monitor memory usage for leaks
• Review recent code changes

---

API Response Codes

• 200 OK - Successful health check (even if status is degraded)
• 500 Internal Server Error - Unrecoverable error
• 503 Service Unavailable - Database unavailable

---

Best Practices

1. Monitoring: Use the quick health check every 5-10 seconds for basic monitoring
2. Dashboards: Use detailed check every 30 seconds for dashboard displays
3. Alerts: Set thresholds on error rates and response times
4. Capacity Planning: Use stats endpoint to identify growth trends
5. Debugging: Use PM2 and SQL status endpoints when investigating issues

---

Related Files

• Frontend: frontend/src/components/AdvancedDashboard.js
• Backend: backend/src/routes/healthDashboard.js
• Tests: tests/advanced-dashboard.spec.js
• Styles: frontend/src/components/AdvancedDashboard.css