Update "Features"
k.eaven committed
1 parent
2b15333bb6
commit
369560ac8b
1 file changed
+248
+248
@@ -0,0 +1,248 @@
|
|||||||
|
# Features
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Pterodisbot provides a comprehensive suite of features for monitoring and managing Pterodactyl game servers through Discord. This page documents each feature in detail.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎮 Server Management
|
||||||
|
|
||||||
|
### Interactive Server Selection
|
||||||
|
- **Dropdown Menu**: `/server_status` command displays an intuitive dropdown with all available game servers
|
||||||
|
- **Server Information**: Each option shows server name and description (truncated to 50 chars)
|
||||||
|
- **Statistics Dashboard**: Shows total servers, online count, and offline count before selection
|
||||||
|
|
||||||
|
### Real-time Power Controls
|
||||||
|
Color-coded button controls for server power management:
|
||||||
|
- 🟢 **Green Start Button** - Powers on the server
|
||||||
|
- 🔴 **Red Stop Button** - Gracefully shuts down the server
|
||||||
|
- 🔵 **Blue Restart Button** - Reboots the server
|
||||||
|
- ⚪ **Grey Show Address Button** - Displays connection information (IP:Port)
|
||||||
|
|
||||||
|
### Connection Information
|
||||||
|
- Instantly view server IP addresses and ports
|
||||||
|
- Fetches default allocation from Pterodactyl panel
|
||||||
|
- Displayed in ephemeral embed (private to requesting user)
|
||||||
|
|
||||||
|
### Multi-channel Embeds
|
||||||
|
- Deploy server status displays across any channels where the bot has permissions
|
||||||
|
- Each server can have one active embed at a time
|
||||||
|
- Automatic cleanup of previous embeds when recreating
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 📊 Server Monitoring
|
||||||
|
|
||||||
|
### Live Status Tracking
|
||||||
|
- Auto-updating embeds display current server state (online/offline/starting)
|
||||||
|
- Color-coded status: 🔵 Blue for online, 🔴 Red for offline
|
||||||
|
- Last updated timestamp on every embed
|
||||||
|
|
||||||
|
### Resource Usage Metrics
|
||||||
|
Real-time monitoring of:
|
||||||
|
| Metric | Description |
|
||||||
|
|--------|-------------|
|
||||||
|
| **CPU Usage** | Percentage with dynamic scaling for multi-core servers |
|
||||||
|
| **Memory Consumption** | Current usage vs. allocated limit (MiB) |
|
||||||
|
| **Disk Space** | Current usage vs. allocated limit (MiB) |
|
||||||
|
| **Network Activity** | Incoming/outgoing traffic (MiB) |
|
||||||
|
| **Uptime Counter** | Human-readable formatting (seconds, minutes, hours, days) |
|
||||||
|
|
||||||
|
### Visual Metrics Graphs
|
||||||
|
- **Combined CPU and Memory Graphs** over the last minute
|
||||||
|
- **6 data points** captured at 10-second intervals
|
||||||
|
- **Discord dark theme-optimized styling** (#2f3136 background)
|
||||||
|
- **Automatic graph generation** and embedding for running servers
|
||||||
|
- **Dynamic CPU scaling** (100% increments) for accurate multi-vCPU visualization
|
||||||
|
- **Trend indicators** (increasing/decreasing/stable) for quick status assessment
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔄 Intelligent Update System
|
||||||
|
|
||||||
|
### Smart Update Triggers
|
||||||
|
Embeds refresh automatically when:
|
||||||
|
| Trigger | Condition |
|
||||||
|
|---------|-----------|
|
||||||
|
| **Power State Change** | Server transitions between offline ↔ starting ↔ running |
|
||||||
|
| **Significant CPU Change** | CPU usage shifts by more than 50% |
|
||||||
|
| **First Detection** | Server detected for the first time |
|
||||||
|
| **Periodic Uptime** | Running servers reach 10-minute intervals |
|
||||||
|
|
||||||
|
### Rate Limit Protection
|
||||||
|
- Built-in delays (0.5s between servers, 1s during refresh) prevent Discord API throttling
|
||||||
|
- Optimized API calls minimize unnecessary requests through change detection
|
||||||
|
- Background task management with asynchronous update loop running every 10 seconds
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔒 Security & Access Control
|
||||||
|
|
||||||
|
### Single-Guild Restriction
|
||||||
|
- Bot operates exclusively in your designated Discord server (`AllowedGuildID`)
|
||||||
|
- All interactions from other guilds are rejected with ephemeral message
|
||||||
|
|
||||||
|
### Role-based Permissions
|
||||||
|
- **"Game Server User" role required** for all server interactions
|
||||||
|
- Exact name match required (case-sensitive)
|
||||||
|
- Role used purely for access control - no special Discord permissions needed
|
||||||
|
|
||||||
|
### Administrator Commands
|
||||||
|
- Special management commands restricted to server administrators
|
||||||
|
- `/refresh_embeds` - Force refresh all embeds
|
||||||
|
- `/purge_embeds` - Permanently delete all embeds
|
||||||
|
|
||||||
|
### Interaction Validation
|
||||||
|
- Every button press and command verified for proper authorization
|
||||||
|
- Guild check + role check on every interaction
|
||||||
|
- Ephemeral error messages for unauthorized attempts
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 💾 Data Persistence
|
||||||
|
|
||||||
|
### Embed Location Storage
|
||||||
|
- Automatically remembers where embeds are posted
|
||||||
|
- Survives bot restarts and crashes
|
||||||
|
- Stored in `embed/embed_locations.json`
|
||||||
|
|
||||||
|
### JSON-based Storage
|
||||||
|
- Human-readable embed tracking format:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"server_identifier": {
|
||||||
|
"channel_id": "123456789012345678",
|
||||||
|
"message_id": "987654321098765432"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Metrics History
|
||||||
|
- Maintains 1 minute of server metrics data (6 data points per server)
|
||||||
|
- Automatic FIFO rotation using `deque(maxlen=6)`
|
||||||
|
- In-memory only (cleared on restart)
|
||||||
|
|
||||||
|
### Automatic Cleanup
|
||||||
|
- Removes tracking for deleted embeds (Discord NotFound errors)
|
||||||
|
- Cleans up metrics for servers that no longer exist in panel
|
||||||
|
- Runs during each update cycle
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🛡️ Reliability Features
|
||||||
|
|
||||||
|
### Comprehensive Error Handling
|
||||||
|
- Graceful recovery from API failures and network issues
|
||||||
|
- Failed embed updates logged but don't crash the update cycle
|
||||||
|
- Structured exception hierarchy for different failure modes
|
||||||
|
|
||||||
|
### Rotating Log Files
|
||||||
|
- Automatic log rotation when file reaches 5MB
|
||||||
|
- Keeps 3 previous log files (`pterodisbot.log.1`, `.2`, `.3`)
|
||||||
|
- UTF-8 encoding for international character support
|
||||||
|
|
||||||
|
### Debug-level Logging
|
||||||
|
- Detailed operational logs for troubleshooting
|
||||||
|
- API calls, state changes, cache operations at DEBUG level
|
||||||
|
- General operations at INFO level
|
||||||
|
|
||||||
|
### Graceful Shutdown
|
||||||
|
- Proper cleanup on SIGINT/SIGTERM signals (Docker-friendly)
|
||||||
|
- Saves embed locations before shutdown
|
||||||
|
- Closes API sessions cleanly
|
||||||
|
|
||||||
|
### Configuration Validation
|
||||||
|
- Startup verification of all required settings
|
||||||
|
- API key format validation (ptlc_/ptla_ or pacc_/papp_)
|
||||||
|
- URL protocol validation (http:// or https://)
|
||||||
|
- Guild ID integer validation
|
||||||
|
|
||||||
|
### API Key Validation
|
||||||
|
- Checks for correct Pterodactyl API key formats
|
||||||
|
- Validates both client and application keys at startup
|
||||||
|
- Clear error messages for misconfigured keys
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🎨 User Interface
|
||||||
|
|
||||||
|
### Color-coded Status
|
||||||
|
- 🔵 **Blue** for online/running servers
|
||||||
|
- 🔴 **Red** for offline/stopped servers
|
||||||
|
- Embed titles reflect current state
|
||||||
|
|
||||||
|
### Ephemeral Interactions
|
||||||
|
- Private responses visible only to command users
|
||||||
|
- `/server_status` dashboard is ephemeral
|
||||||
|
- Button responses are ephemeral
|
||||||
|
- Address display is ephemeral
|
||||||
|
|
||||||
|
### Real-time Feedback
|
||||||
|
- Instant confirmation messages for all actions
|
||||||
|
- Start/Stop/Restart show "is starting...", "is stopping...", "is restarting..."
|
||||||
|
- Error messages include API response details
|
||||||
|
|
||||||
|
### Persistent Controls
|
||||||
|
- Server control buttons remain functional indefinitely
|
||||||
|
- Views created with `timeout=None` for infinite persistence
|
||||||
|
- Survives bot restarts (re-registered on startup)
|
||||||
|
|
||||||
|
### Responsive Design
|
||||||
|
- Clean, Discord-optimized embed layouts
|
||||||
|
- Code-block formatting for resource usage tables
|
||||||
|
- Proper field inline/block arrangement
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 🔧 Administrator Tools
|
||||||
|
|
||||||
|
### Bulk Embed Refresh (`/refresh_embeds`)
|
||||||
|
- Force-refresh all server status embeds with one command
|
||||||
|
- Recreates all tracked embeds with fresh data
|
||||||
|
- Deletes old embed messages to prevent duplication
|
||||||
|
- Updates embed tracking storage
|
||||||
|
- Provides statistics on deleted and created embeds
|
||||||
|
|
||||||
|
### Complete Purge System (`/purge_embeds`)
|
||||||
|
- Remove all bot embeds from the server with detailed statistics
|
||||||
|
- Real-time progress updates during multi-embed operations
|
||||||
|
- Shows deleted, missing, and error counts
|
||||||
|
- Success rate percentage calculation
|
||||||
|
- Clears embed tracking file
|
||||||
|
|
||||||
|
### Progress Tracking
|
||||||
|
- Real-time progress updates during multi-embed operations
|
||||||
|
- Updates every 5 embeds processed
|
||||||
|
- Ephemeral progress embed with live counters
|
||||||
|
|
||||||
|
### Comprehensive Logging
|
||||||
|
- All administrative actions logged with user attribution
|
||||||
|
- Command invocation, success/failure, statistics
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feature Comparison Table
|
||||||
|
|
||||||
|
| Feature | Traditional | Docker | Kubernetes |
|
||||||
|
|---------|-------------|--------|------------|
|
||||||
|
| Server Management | ✅ | ✅ | ✅ |
|
||||||
|
| Real-time Monitoring | ✅ | ✅ | ✅ |
|
||||||
|
| Metrics Graphs | ✅ | ✅ | ✅ |
|
||||||
|
| Role-based Access | ✅ | ✅ | ✅ |
|
||||||
|
| Persistent Embeds | ✅ | ✅ | ✅ |
|
||||||
|
| Admin Tools | ✅ | ✅ | ✅ |
|
||||||
|
| Auto-restart | Manual | `--restart unless-stopped` | `restartPolicy: Always` |
|
||||||
|
| Log Persistence | Local files | Volume mount | PVC |
|
||||||
|
| Config Management | config.ini | Env vars / Volume | Secrets |
|
||||||
|
| Scaling | Manual | Manual | HPA support |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Pages
|
||||||
|
|
||||||
|
- [Architecture](/Architecture) - System design and data flow
|
||||||
|
- [Installation](/Installation) - Deployment guides
|
||||||
|
- [Configuration](/Configuration) - Config options
|
||||||
|
- [Usage](/Usage) - Commands and workflows
|
||||||
|
- [Contributing](/Contributing) - Development guidelines
|
||||||
Reference in new issue
Block a user