drone-detector/docs/HEALTH_PROBE_SIMULATOR.md

# Health Probe Simulator

The Health Probe Simulator continuously sends heartbeat messages from all devices to test the offline detection feature of the drone detection system.

## Features

- 🔄 **Continuous Monitoring**: Sends heartbeats every minute (configurable)
- 📊 **Configurable Failure Rate**: Simulates device failures to test offline detection
- 🎯 **Real Device Integration**: Uses actual devices from your system
- 📈 **Statistics Reporting**: Shows success/failure rates for each cycle
- 🐳 **Docker Support**: Can run as a container alongside the main system

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PROBE_FAILRATE` | `30` | Percentage of probes that should fail (0-100) |
| `PROBE_INTERVAL_SECONDS` | `60` | Interval between probe cycles in seconds |
| `API_BASE_URL` | `https://selfservice.cqers.com/drones/api` | API endpoint URL |

### .env File

Add these lines to your `.env` file:

```bash
# Health Probe Simulator Configuration
PROBE_FAILRATE=30
PROBE_INTERVAL_SECONDS=60
API_BASE_URL=https://selfservice.cqers.com/drones/api
```

## Usage

### Option 1: Docker Compose (Recommended)

Start the health probe simulator as a Docker service:

```bash
# Start with health probe simulator
docker-compose --profile healthprobe up -d

# View logs
docker-compose logs -f healthprobe

# Stop the service
docker-compose --profile healthprobe down
```

### Option 2: Local Python Script

Run directly with Python:

```bash
# Linux/Mac
./start-healthprobe.sh

# Windows
start-healthprobe.bat

# Or directly with Python
python3 health_probe_simulator.py
```

### Option 3: Manual Docker Build

```bash
# Build the health probe image
docker build -f Dockerfile.healthprobe -t health-probe-simulator .

# Run the container
docker run -d \
  --name health-probe \
  --network uamils_drone-network \
  -e PROBE_FAILRATE=30 \
  -e PROBE_INTERVAL_SECONDS=60 \
  -e API_BASE_URL=http://backend:3001/api \
  health-probe-simulator
```

## Output Example

```
🏥 DRONE DETECTION SYSTEM - HEALTH PROBE SIMULATOR
============================================================

📋 Configuration:
   PROBE_FAILRATE: 30%
   PROBE_INTERVAL_SECONDS: 60s
   API_BASE_URL: https://selfservice.cqers.com/drones/api

🔧 Health Probe Simulator Configuration:
   API URL: https://selfservice.cqers.com/drones/api
   Probe Interval: 60 seconds
   Failure Rate: 30%

📡 Fetched 4 devices for health monitoring
   - Device 1941875381: Arlanda Airport Detector (Arlanda Airport Terminal 2)
   - Device 1725834521: Royal Castle Detector (Royal Castle Stockholm)
   - Device 1456789123: Muskö Naval Base Detector (Muskö Naval Base)
   - Device 1987654321: Gothenburg Port Detector (Port of Gothenburg)

🔄 Starting probe cycle at 2025-08-19 14:30:00
   Probing 4 devices...

💓 Device 1941875381: Heartbeat sent successfully (Arlanda Airport Detector - Arlanda Airport Terminal 2)
💔 Simulating probe failure for Device 1725834521 (30% failure rate)
💓 Device 1456789123: Heartbeat sent successfully (Muskö Naval Base Detector - Muskö Naval Base)
💔 Simulating probe failure for Device 1987654321 (30% failure rate)

📊 Probe Cycle Summary:
   ✅ Successful: 2
   ❌ Failed: 2
   📈 Success Rate: 50.0%
   🎯 Target Failure Rate: 30%
   ⏰ Next cycle in 60 seconds
```

## Testing Offline Detection

The health probe simulator is perfect for testing your system's offline detection capabilities:

1. **Set Failure Rate**: Adjust `PROBE_FAILRATE` to control how many devices appear offline
2. **Monitor Dashboard**: Watch the map view to see devices changing status
3. **Check Alerts**: Verify that offline device alerts are triggered
4. **Test Recovery**: Failed devices will randomly come back online in subsequent cycles

## Use Cases

- **🧪 Testing**: Verify offline detection works correctly
- **🎭 Demo**: Show system behavior during device failures
- **📊 Load Testing**: Generate consistent heartbeat traffic
- **🔧 Development**: Test heartbeat handling and device status logic

## Stopping the Simulator

### Docker Compose
```bash
docker-compose --profile healthprobe down
```

### Local Script
Press `Ctrl+C` to stop the simulator gracefully.

### Docker Container
```bash
docker stop health-probe
docker rm health-probe
```

## Troubleshooting

### Common Issues

1. **Connection Errors**: Check API_BASE_URL and network connectivity
2. **Authentication Errors**: Ensure the API endpoint doesn't require authentication for heartbeats
3. **High CPU Usage**: Increase PROBE_INTERVAL_SECONDS to reduce frequency

### Logs

Check the container logs for detailed output:
```bash
docker-compose logs healthprobe
```

## Integration with Main System

The health probe simulator:
- ✅ Uses the same heartbeat API as real devices
- ✅ Automatically discovers all devices in your system
- ✅ Respects your configured offline detection timeouts
- ✅ Generates realistic device status changes
- ✅ Helps validate your monitoring and alerting systems