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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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
```javascript
<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
```javascript
import AdvancedDashboard from './components/AdvancedDashboard';

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

### Checking Health Programmatically
```javascript
// 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:
```bash
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`