mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-02-18 00:17:39 +01:00
docs: Add documentation for Pulse 5.0 features
- AI.md: Pulse AI assistant (chat, patrol, auto-fix) - METRICS_HISTORY.md: Persistent metrics storage - MAIL_GATEWAY.md: PMG monitoring support - AUTO_UPDATE.md: One-click updates - Updated README.md with 5.0 features section
This commit is contained in:
rcourtman
123
docs/AI.md
Normal file
123
docs/AI.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# Pulse AI
|
||||
|
||||
Pulse AI is an intelligent monitoring assistant that helps you understand and manage your infrastructure through natural language conversations, proactive monitoring, and automated issue resolution.
|
||||
|
||||
## Features
|
||||
|
||||
### Chat Assistant
|
||||
Ask questions about your infrastructure in plain English:
|
||||
- "What's using the most CPU right now?"
|
||||
- "Show me VMs with high memory usage"
|
||||
- "Why is my backup failing?"
|
||||
- "Summarize the health of my cluster"
|
||||
|
||||
### Patrol Mode
|
||||
Automated monitoring that runs on a schedule to:
|
||||
- Analyze resource utilization patterns
|
||||
- Detect potential issues before they cause problems
|
||||
- Generate actionable recommendations
|
||||
- Track trends over time
|
||||
|
||||
### Auto-Fix
|
||||
Automatically resolve common issues:
|
||||
- Restart stuck services
|
||||
- Clear disk space
|
||||
- Restart unresponsive containers
|
||||
- Apply recommended optimizations
|
||||
|
||||
### Predictive Intelligence
|
||||
- Identify resources trending toward problems
|
||||
- Forecast disk space exhaustion
|
||||
- Detect unusual patterns
|
||||
- Alert on anomalies
|
||||
|
||||
## Configuration
|
||||
|
||||
### Enable Pulse AI
|
||||
|
||||
1. Navigate to **Settings → AI**
|
||||
2. Toggle **Enable Pulse AI**
|
||||
3. Configure your AI provider
|
||||
|
||||
### Supported Providers
|
||||
|
||||
| Provider | Models | Notes |
|
||||
|----------|--------|-------|
|
||||
| **OpenAI** | GPT-4, GPT-4 Turbo, GPT-3.5 | Recommended for best results |
|
||||
| **Anthropic** | Claude 3 Opus, Sonnet, Haiku | Excellent for complex analysis |
|
||||
| **Ollama** | Llama 3, Mistral, etc. | Self-hosted, privacy-focused |
|
||||
| **OpenRouter** | Multiple models | Pay-per-use routing |
|
||||
| **Custom** | Any OpenAI-compatible API | For enterprise deployments |
|
||||
|
||||
### API Key Setup
|
||||
|
||||
```bash
|
||||
# Environment variable (recommended for production)
|
||||
export PULSE_AI_PROVIDER=openai
|
||||
export PULSE_AI_API_KEY=sk-...
|
||||
|
||||
# Or configure via Settings UI
|
||||
```
|
||||
|
||||
### Patrol Configuration
|
||||
|
||||
| Setting | Default | Description |
|
||||
|---------|---------|-------------|
|
||||
| Patrol Enabled | Off | Run automated checks |
|
||||
| Patrol Interval | 30 minutes | How often to run patrol |
|
||||
| Auto-Fix Enabled | Off | Allow automatic remediation |
|
||||
| Auto-Fix Model | Same as chat | Model for auto-fix decisions |
|
||||
|
||||
## Usage
|
||||
|
||||
### Chat Interface
|
||||
Access the AI chat from the bottom-right corner of any page. Type your question and press Enter.
|
||||
|
||||
**Example queries:**
|
||||
```
|
||||
"What VMs are using more than 80% memory?"
|
||||
"Show me the status of all backups"
|
||||
"Why is node pve1 showing high load?"
|
||||
"Compare resource usage between this week and last week"
|
||||
```
|
||||
|
||||
### Context Selection
|
||||
Click on any resource (VM, container, host) to add it to the AI context. This helps the AI provide more specific answers.
|
||||
|
||||
### Patrol Reports
|
||||
When Patrol is enabled, Pulse AI will:
|
||||
1. Run periodic health checks
|
||||
2. Generate findings (issues, warnings, info)
|
||||
3. Offer to auto-fix issues (if enabled)
|
||||
4. Track trends over time
|
||||
|
||||
## Cost Tracking
|
||||
|
||||
Track AI API usage in **Settings → AI → Cost Dashboard**:
|
||||
- Daily/monthly usage statistics
|
||||
- Cost breakdown by feature
|
||||
- Usage trends over time
|
||||
|
||||
## Privacy & Security
|
||||
|
||||
- **Data stays local**: Only resource metadata is sent to AI providers
|
||||
- **No training**: Your data is never used for model training
|
||||
- **Audit logging**: All AI interactions are logged
|
||||
- **Self-hosted option**: Use Ollama for complete data privacy
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### AI not responding
|
||||
1. Check API key is configured correctly
|
||||
2. Verify network connectivity to AI provider
|
||||
3. Check Settings → AI for error messages
|
||||
|
||||
### Patrol not running
|
||||
1. Ensure Patrol is enabled in Settings
|
||||
2. Check system resource availability
|
||||
3. Review logs: `journalctl -u pulse -f`
|
||||
|
||||
### Auto-fix not working
|
||||
1. Enable Auto-Fix in Settings → AI
|
||||
2. Verify the connected agents have execute permissions
|
||||
3. Check the Auto-Fix model is configured
|
||||
141
docs/AUTO_UPDATE.md
Normal file
141
docs/AUTO_UPDATE.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# Automatic Updates
|
||||
|
||||
Pulse 5.0 introduces one-click updates for supported deployment types, making it easy to keep your monitoring system up to date.
|
||||
|
||||
## Supported Deployment Types
|
||||
|
||||
| Deployment | Auto-Update | Method |
|
||||
|------------|-------------|--------|
|
||||
| **ProxmoxVE LXC** | ✅ Yes | In-app update button |
|
||||
| **Systemd Service** | ✅ Yes | In-app update button |
|
||||
| **Docker** | ❌ Manual | Pull new image |
|
||||
| **Source Build** | ❌ Manual | Git pull + rebuild |
|
||||
|
||||
## Using One-Click Updates
|
||||
|
||||
### When an Update is Available
|
||||
|
||||
1. Navigate to **Settings → System Updates**
|
||||
2. If an update is available, you'll see an **"Install Update"** button
|
||||
3. Click the button to open the confirmation dialog
|
||||
4. Review the update details:
|
||||
- Current version → New version
|
||||
- Estimated time
|
||||
- Changelog highlights
|
||||
5. Click **"Install Update"** to begin
|
||||
|
||||
### Update Process
|
||||
|
||||
1. **Download**: New version is downloaded
|
||||
2. **Backup**: Current installation is backed up
|
||||
3. **Apply**: Files are updated
|
||||
4. **Restart**: Service restarts automatically
|
||||
5. **Verify**: Health check confirms success
|
||||
|
||||
### Progress Tracking
|
||||
|
||||
A real-time progress modal shows:
|
||||
- Current step
|
||||
- Download progress
|
||||
- Any warnings or errors
|
||||
- Automatic page reload on success
|
||||
|
||||
## Configuration
|
||||
|
||||
### Update Preferences
|
||||
|
||||
In **Settings → System Updates**:
|
||||
|
||||
| Setting | Description |
|
||||
|---------|-------------|
|
||||
| **Update Channel** | Stable (recommended) or Release Candidate |
|
||||
| **Auto-Check** | Automatically check for updates daily |
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Disable auto-update check
|
||||
PULSE_AUTO_UPDATE_CHECK=false
|
||||
|
||||
# Use release candidate channel
|
||||
PULSE_UPDATE_CHANNEL=rc
|
||||
```
|
||||
|
||||
## Manual Update Methods
|
||||
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
# Pull latest image
|
||||
docker pull ghcr.io/rcourtman/pulse:latest
|
||||
|
||||
# Restart container
|
||||
docker-compose down && docker-compose up -d
|
||||
```
|
||||
|
||||
### ProxmoxVE LXC (Manual)
|
||||
|
||||
```bash
|
||||
# Inside the container
|
||||
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
### Systemd Service (Manual)
|
||||
|
||||
```bash
|
||||
# Download new release
|
||||
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
### Source Build
|
||||
|
||||
```bash
|
||||
cd /opt/pulse
|
||||
git pull
|
||||
make build
|
||||
sudo systemctl restart pulse
|
||||
```
|
||||
|
||||
## Rollback
|
||||
|
||||
If an update causes issues:
|
||||
|
||||
### Automatic Rollback
|
||||
Pulse creates a backup before updating. If the update fails:
|
||||
1. The previous version is automatically restored
|
||||
2. Service restarts with the old version
|
||||
3. Error details are logged
|
||||
|
||||
### Manual Rollback
|
||||
```bash
|
||||
# Backups are stored in /etc/pulse/backups/
|
||||
ls /etc/pulse/backups/
|
||||
|
||||
# Restore a specific backup
|
||||
sudo /opt/pulse/scripts/restore-backup.sh /etc/pulse/backups/pulse-backup-20250101.tar.gz
|
||||
```
|
||||
|
||||
## Update History
|
||||
|
||||
View past updates in **Settings → System Updates → Update History**:
|
||||
- Previous versions installed
|
||||
- Update timestamps
|
||||
- Success/failure status
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Update button not showing
|
||||
1. Check if your deployment supports auto-update
|
||||
2. Verify an update is actually available
|
||||
3. Ensure you have the latest frontend loaded (hard refresh)
|
||||
|
||||
### Update failed
|
||||
1. Check the error message in the progress modal
|
||||
2. Review logs: `journalctl -u pulse -n 100`
|
||||
3. Verify disk space is available
|
||||
4. Check network connectivity to GitHub
|
||||
|
||||
### Service won't restart after update
|
||||
1. Check systemd status: `systemctl status pulse`
|
||||
2. View recent logs: `journalctl -u pulse -f`
|
||||
3. Manually restore from backup if needed
|
||||
99
docs/MAIL_GATEWAY.md
Normal file
99
docs/MAIL_GATEWAY.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# Proxmox Mail Gateway (PMG) Monitoring
|
||||
|
||||
Pulse 5.0 adds support for monitoring Proxmox Mail Gateway instances alongside your PVE and PBS infrastructure.
|
||||
|
||||
## Features
|
||||
|
||||
- **Mail Queue Monitoring**: Track active, deferred, and held messages
|
||||
- **Spam Statistics**: View spam detection rates and virus blocks
|
||||
- **Cluster Status**: Monitor PMG cluster node health
|
||||
- **Quarantine Overview**: See quarantine size and pending reviews
|
||||
|
||||
## Adding a PMG Instance
|
||||
|
||||
### Via Settings UI
|
||||
|
||||
1. Navigate to **Settings → Proxmox**
|
||||
2. Click **Add Node**
|
||||
3. Select **Proxmox Mail Gateway** as the type
|
||||
4. Enter connection details:
|
||||
- Host: Your PMG IP or hostname
|
||||
- Port: 8006 (default)
|
||||
- API Token ID: e.g., `root@pam!pulse`
|
||||
- API Token Secret: Your token secret
|
||||
|
||||
### Via Discovery
|
||||
|
||||
Pulse can automatically discover PMG instances on your network:
|
||||
|
||||
1. Go to **Settings → Discovery**
|
||||
2. Enable network discovery
|
||||
3. PMG instances on port 8006 will be detected
|
||||
4. Click to add discovered instances
|
||||
|
||||
## API Token Setup on PMG
|
||||
|
||||
Create an API token on your PMG server:
|
||||
|
||||
```bash
|
||||
# SSH to your PMG server
|
||||
pveum user token add root@pam pulse --privsep 0
|
||||
|
||||
# Note the token secret - it's only shown once!
|
||||
```
|
||||
|
||||
Required permissions:
|
||||
- `Sys.Audit` - Read system status
|
||||
- `Datastore.Audit` - Read mail statistics
|
||||
|
||||
## Dashboard
|
||||
|
||||
The Mail Gateway tab shows:
|
||||
|
||||
| Metric | Description |
|
||||
|--------|-------------|
|
||||
| **Mail Processed** | Total emails processed today |
|
||||
| **Spam Rate** | Percentage of spam detected |
|
||||
| **Virus Blocked** | Malicious emails caught |
|
||||
| **Queue Depth** | Messages pending delivery |
|
||||
| **Quarantine Size** | Emails in quarantine |
|
||||
|
||||
### Status Indicators
|
||||
|
||||
- 🟢 **Healthy**: Normal operation
|
||||
- 🟡 **Warning**: Queue building up or high spam rate
|
||||
- 🔴 **Critical**: Delivery issues or cluster problems
|
||||
|
||||
## Alerts
|
||||
|
||||
Configure alerts for PMG metrics in **Settings → Alerts**:
|
||||
|
||||
- Queue depth exceeding threshold
|
||||
- Spam rate spike
|
||||
- Delivery failures
|
||||
- Cluster node offline
|
||||
|
||||
## Multi-Instance Support
|
||||
|
||||
Monitor multiple PMG instances from a single Pulse dashboard:
|
||||
|
||||
- Compare spam rates across gateways
|
||||
- Aggregate mail statistics
|
||||
- View cluster-wide health
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection refused
|
||||
1. Verify PMG is accessible on port 8006
|
||||
2. Check firewall rules
|
||||
3. Ensure API token has correct permissions
|
||||
|
||||
### No statistics showing
|
||||
1. Wait for initial data collection (may take 1-2 polling cycles)
|
||||
2. Verify PMG has mail activity
|
||||
3. Check Pulse logs for API errors
|
||||
|
||||
### Cluster nodes missing
|
||||
1. PMG cluster must be properly configured
|
||||
2. API token needs cluster-wide permissions
|
||||
3. All nodes must be reachable from Pulse
|
||||
87
docs/METRICS_HISTORY.md
Normal file
87
docs/METRICS_HISTORY.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# Metrics History
|
||||
|
||||
Pulse 5.0 introduces persistent metrics history, allowing you to view historical resource usage data and trends over time.
|
||||
|
||||
## Features
|
||||
|
||||
- **Persistent Storage**: Metrics are saved to disk and survive restarts
|
||||
- **Configurable Retention**: Set how long to keep different metric types
|
||||
- **Trend Analysis**: View resource usage patterns over time
|
||||
- **Spark Lines**: See at-a-glance trends in the dashboard
|
||||
|
||||
## Configuration
|
||||
|
||||
### Retention Settings
|
||||
|
||||
Configure retention periods in **Settings → General → Metrics History**:
|
||||
|
||||
| Metric Type | Default | Description |
|
||||
|-------------|---------|-------------|
|
||||
| **Host Metrics** | 7 days | CPU, memory, disk for hypervisors |
|
||||
| **Guest Metrics** | 7 days | VM and container metrics |
|
||||
| **Container Metrics** | 3 days | Docker/Podman container stats |
|
||||
| **Aggregate Metrics** | 30 days | Cluster-wide summaries |
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Override via environment
|
||||
PULSE_METRICS_HOST_RETENTION_DAYS=14
|
||||
PULSE_METRICS_GUEST_RETENTION_DAYS=14
|
||||
PULSE_METRICS_CONTAINER_RETENTION_DAYS=7
|
||||
PULSE_METRICS_AGGREGATE_RETENTION_DAYS=60
|
||||
```
|
||||
|
||||
## Storage
|
||||
|
||||
Metrics are stored in `/etc/pulse/data/metrics/` (or your configured data directory).
|
||||
|
||||
### Disk Usage
|
||||
|
||||
Approximate storage requirements:
|
||||
- ~1 KB per resource per hour
|
||||
- 10 hosts × 50 guests × 7 days ≈ 8 MB
|
||||
|
||||
### Database Maintenance
|
||||
|
||||
Pulse automatically:
|
||||
- Compacts old data
|
||||
- Prunes metrics beyond retention period
|
||||
- Optimizes storage during low-usage periods
|
||||
|
||||
## API Access
|
||||
|
||||
Query historical metrics via the API:
|
||||
|
||||
```bash
|
||||
# Get metrics for a specific resource
|
||||
curl -H "X-API-Token: $TOKEN" \
|
||||
"http://localhost:7655/api/metrics/history?resource=vm-100&hours=24"
|
||||
|
||||
# Get aggregated cluster metrics
|
||||
curl -H "X-API-Token: $TOKEN" \
|
||||
"http://localhost:7655/api/metrics/history?type=aggregate&days=7"
|
||||
```
|
||||
|
||||
## Visualization
|
||||
|
||||
### Dashboard Sparklines
|
||||
The dashboard shows 24-hour trend sparklines for each resource, updating in real-time.
|
||||
|
||||
### Detailed Charts
|
||||
Click on any resource to see detailed historical charts with:
|
||||
- Selectable time ranges (1h, 6h, 24h, 7d, 30d)
|
||||
- Multiple metric overlays (CPU, memory, disk, network)
|
||||
- Zoom and pan controls
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Metrics not persisting
|
||||
1. Check data directory permissions
|
||||
2. Verify disk space availability
|
||||
3. Check logs: `journalctl -u pulse | grep metrics`
|
||||
|
||||
### High disk usage
|
||||
1. Reduce retention periods in Settings
|
||||
2. Exclude low-value resources from history
|
||||
3. Run manual cleanup: Settings → General → Clear Old Metrics
|
||||
@@ -26,6 +26,14 @@ Welcome to the Pulse documentation portal. Here you'll find everything you need
|
||||
|
||||
- **[Security Policy](../SECURITY.md)** – The core security model (Encryption, Auth, API Scopes).
|
||||
|
||||
## ✨ New in 5.0
|
||||
|
||||
- **[Pulse AI](AI.md)** – Intelligent monitoring assistant with chat, patrol mode, and auto-fix.
|
||||
- **[Metrics History](METRICS_HISTORY.md)** – Persistent metrics storage with configurable retention.
|
||||
- **[Mail Gateway](MAIL_GATEWAY.md)** – Proxmox Mail Gateway (PMG) monitoring.
|
||||
- **[Auto Updates](AUTO_UPDATE.md)** – One-click updates for supported deployments.
|
||||
- **[Kubernetes](KUBERNETES.md)** – Complete K8s cluster monitoring via agents.
|
||||
|
||||
## 📡 Monitoring & Agents
|
||||
|
||||
- **[Unified Agent](UNIFIED_AGENT.md)** – Single binary for Host and Docker monitoring.
|
||||
|
||||
Reference in New Issue
Block a user