danvics/Pulse
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: Add documentation for Pulse 5.0 features

Browse source 
- 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 2025-12-13 15:27:36 +00:00
parent 702b39740d
commit 4f925f5674
5 changed files with 458 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

123
docs/AI.md Normal file
View 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
View 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
View 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
View 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

8
docs/README.md
View file

@ -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). - **[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 ## 📡 Monitoring & Agents
- **[Unified Agent](UNIFIED_AGENT.md)** – Single binary for Host and Docker monitoring. - **[Unified Agent](UNIFIED_AGENT.md)** – Single binary for Host and Docker monitoring.