PerfMonitor

⚡ Modern Performance Monitoring for Minecraft Server Networks

Live TPS • MSPT • RAM • CPU Monitoring
PoloCloud Integration • Redis Support • Web Dashboards

📖 Documentation • 🚀 Quick Start • ⚙️ Configuration • 🤝 Contributing

📑 Table of Contents

✨ Features
📦 Modules
☁️ PoloCloud Integration
🚀 Quick Start
⚙️ Configuration
🎮 Commands
📊 Dashboard
🔧 Advanced Usage
🛠️ Building
🤝 Contributing
📄 License

✨ Features

🌐 Web Dashboard Real-time charts powered by Chart.js TPS, MSPT, RAM & CPU visualizations Responsive design for mobile & desktop	☁️ PoloCloud Integration Automatic server & proxy detection No manual configuration needed Graceful fallback support
🔴 Redis Support Pub/Sub multi-server communication Cross-server metrics sharing Real-time command sync	🔗 BungeeCord Messaging Plugin messaging channel support Centralized proxy monitoring Network-wide statistics
📈 Smart Metrics Current values + averages 200-point history charts Auto-downsampling for performance	💬 Discord Alerts Critical performance warnings Configurable thresholds Webhook notifications

📦 Modules

Module	Platform	Description	Output
EasyPerfMonitor	Spigot/Paper/Folia	BungeeCord messaging integration	`EasyPerfMonitor-2.0.0-SNAPSHOT.jar`
EasyPerfMonitorStandalone	Spigot/Paper/Folia	Redis pub/sub support	`EasyPerfMonitorStandalone-2.0.0.jar`
EasyPrefMonitorBungee	BungeeCord	Centralized network monitoring	`BungeePerfMonitor-2.0.jar`

🎯 Which Module Should I Use?

┌─────────────────────────────────────────────────────────────┐
│  Your Setup                              →  Use Module      │
├─────────────────────────────────────────────────────────────┤
│  BungeeCord Network + PoloCloud          →  EasyPerfMonitor │
│  Multiple Servers + Redis                →  Standalone      │
│  BungeeCord Proxy (central monitoring)    →  Bungee Module   │
│  Single Server                           →  Any module       │
└─────────────────────────────────────────────────────────────┘

☁️ PoloCloud Integration

🔄 How It Works

┌──────────────────────────────────────────────────────────────┐
│                     Plugin Startup                            │
│                           │                                   │
│                           ▼                                   │
│              ┌─────────────────────────┐                      │
│              │  PoloCloud Available?   │                      │
│              └─────────────────────────┘                      │
│                    │          │                              │
│               YES  │          │  NO                          │
│                    ▼          ▼                              │
│    ┌────────────────────┐  ┌────────────────────┐            │
│    │ Auto-detect:       │  │ Use config.yml:    │            │
│    │ • Service Name     │  │ • server-name:     │            │
│    │ • Group Name       │  │   "lobby-1"        │            │
│    │ • Service ID       │  │                    │            │
│    └────────────────────┘  └────────────────────┘            │
└──────────────────────────────────────────────────────────────┘

📝 Configuration

# Automatic PoloCloud detection
polocloud:
  enabled: true    # Enable auto-detection

# Fallback when PoloCloud unavailable
redis:
  server-name: "server-1"  # Manual fallback

🎯 Benefits

Without PoloCloud	With PoloCloud
❌ Manual config for each server	✅ Automatic detection
❌ Easy to misconfigure	✅ Zero configuration
❌ Restart required for name changes	✅ Dynamic updates

🚀 Quick Start

📋 Prerequisites

Requirement	Version	Notes
☕ Java	8+	Required
📦 Maven	3.6+	For building
🎮 Spigot/Paper/Folia	1.8.8+	Required
☁️ PoloCloud	Any	Optional
🔴 Redis	5.0+	Optional

⚡ Installation

# 1️⃣ Clone & Build
git clone https://github.com/Quertixx-de/PerfMonitor.git
cd PerfMonitor
mvn clean package

# 2️⃣ Install (choose your module)
cp EasyPerfMonitor/target/EasyPerfMonitor-*.jar /path/to/spigot/plugins/
# OR
cp EasyPerfMonitorStandalone/target/EasyPerfMonitorStandalone-*.jar /path/to/spigot/plugins/
# OR  
cp EasyPrefMonitorBungee/target/BungeePerfMonitor-*.jar /path/to/bungeecord/plugins/

# 3️⃣ Start server & check logs
# ✓ PoloCloud erkannt!
# ✓ Web Dashboard: http://localhost:8080

# 4️⃣ Open Dashboard
#http://your-server:8080

🎮 First Steps

Step	Action	Result
1	Start server	Plugin loads, detects PoloCloud
2	Check console	Look for `✓ PoloCloud erkannt!`
3	Open browser	Navigate to `http://localhost:8080`
4	Run `/perf`	See current metrics in chat

⚙️ Configuration

📄 EasyPerfMonitor (Spigot/Paper)

# ╔═══════════════════════════════════════════╗
# ║        PoloCloud Integration              ║
# ╚═══════════════════════════════════════════╝
polocloud:
  enabled: true        # Auto-detect server from PoloCloud

# ╔═══════════════════════════════════════════╗
# ║           Redis Configuration             ║
# ╚═══════════════════════════════════════════╝
redis:
  enabled: false       # Enable Redis pub/sub
  host: "localhost"
  port: 6379
  password: ""
  server-name: "server-1"    # Fallback identifier
  subscribe-to-metrics: false

# ╔═══════════════════════════════════════════╗
# ║          Web Dashboard Settings           ║
# ╚═══════════════════════════════════════════╝
web:
  host: "0.0.0.0"      # Bind address
  port: 8080          # Dashboard port
  addresses: []       # External URLs

# ╔═══════════════════════════════════════════╗
# ║        Performance Monitoring             ║
# ╚═══════════════════════════════════════════╝
monitoring:
  update-interval: 100       # Ticks (5 seconds)
  auto-export-interval: 60   # Seconds
  max-history-points: 200

📄 EasyPrefMonitorBungee (BungeeCord)

# ╔═══════════════════════════════════════════╗
# ║        PoloCloud Integration              ║
# ╚═══════════════════════════════════════════╝
polocloud:
  enabled: true        # Auto-detect proxy

# ╔═══════════════════════════════════════════╗
# ║           Web Dashboard Port              ║
# ╚═══════════════════════════════════════════╝
web:
  port: 8081          # Proxy dashboard port

# ╔═══════════════════════════════════════════╗
# ║          Discord Webhook Alerts           ║
# ╚═══════════════════════════════════════════╝
discord:
  enabled: false
  webhook_url: ""
  thresholds:
    critical_tps: 18.0
    critical_mspt: 50.0
    critical_ram_percent: 90.0

🎮 Commands

Command	Description	Permission
`/perf`	Show current performance stats	`easyperf.use`
`/perf now`	Display live performance snapshot	`easyperf.use`
`/perf export`	Export performance history to JSON	`easyperf.admin`
`/perf web`	Get dashboard URL(s)	`easyperf.use`
`/perf redis`	Check Redis connection status	`easyperf.use`
`/perf reload`	Reload configuration	`easyperf.admin`

📊 Performance Output Example

╔════════════════════════════════════════════╗
║          📊 Server Performance             ║
╠════════════════════════════════════════════╣
║  TPS:   20.00 ████ 20/20                   ║
║  MSPT:  12.5ms ▓▓░░░░░░░░                   ║
║  RAM:   512MB / 2048MB  (25%)              ║
║  CPU:   15.3%                              ║
║  Chunks: 248    Entities: 1,842             ║
║  Players: 12/100                            ║
╚════════════════════════════════════════════╝

📊 Dashboard

🖥️ Web Interface

┌─────────────────────────────────────────────────────────┐
│  📈 PerfMonitor Dashboard                        [Live]  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   ┌─────────────────┐    ┌─────────────────┐           │
│   │  TPS Chart      │    │  MSPT Chart     │           │
│   │  ▓▓▓▓▓▓▓▓▓░░    │    │  ▓▓▓░░░░░░░░    │           │
│   │  Current: 20.0  │    │  Current: 12ms  │           │
│   │  Avg: 19.8      │    │  Avg: 15ms      │           │
│   └─────────────────┘    └─────────────────┘           │
│                                                         │
│   ┌─────────────────┐    ┌─────────────────┐           │
│   │  RAM Usage      │    │  CPU Usage      │           │
│   │  ▓▓▓▓▓░░░░░░    │    │  ▓▓▓░░░░░░░░    │           │
│   │  512/2048 MB    │    │  15.3%          │           │
│   │  Usage: 25%     │    │  Avg: 18.5%     │           │
│   └─────────────────┘    └─────────────────┘           │
│                                                         │
│  Server: lobby-1 (PoloCloud) • Updated: 2s ago         │
└─────────────────────────────────────────────────────────┘

📈 Available Metrics

Metric	Description	Update Rate	History
TPS	Ticks Per Second	Every tick	1200 points (1min)
MSPT	MS Per Tick	Every tick	200 points
RAM	Memory Usage	5 seconds	200 points
CPU	Processor Load	5 seconds	200 points
Chunks	Loaded Chunks	5 seconds	-
Entities	Entity Count	5 seconds	-
Players	Online Players	5 seconds	-

🔧 Advanced Usage

🔌 API Integration

// Get PoloCloud information
PoloCloudHook hook = EasyPerfMonitor.getInstance().getPoloCloudHook();

if (hook != null && hook.isAvailable()) {
    String serviceName = hook.getServiceName();   // e.g., "lobby-1"
    String groupName = hook.getGroupName();         // e.g., "lobby"
    int serviceId = hook.getServiceId();           // e.g., 1
}

// Get performance metrics
double tps = EasyPerfMonitor.getTPSRaw();
double mspt = EasyPerfMonitor.getMSPTRaw();
int chunks = EasyPerfMonitor.getTotalChunks();
int entities = EasyPerfMonitor.getTotalEntities();

📡 Redis Data Format

Metrics Message:

{
  "server": "lobby-1",
  "timestamp": 1706983200000,
  "tps": 20.0,
  "tps1m": 19.8,
  "tps5m": 19.5,
  "tps15m": 19.2,
  "mspt": 12.5,
  "ramUsed": 512,
  "ramMax": 2048,
  "cpuUsage": 15.3,
  "chunks": 248,
  "entities": 1842,
  "players": 12
}

🛠️ Building

📦 Build All Modules

# Clone repository
git clone https://github.com/Quertixx-de/PerfMonitor.git
cd PerfMonitor

# Build all modules
mvn clean package

# Output locations:
# 📦 EasyPerfMonitor/target/EasyPerfMonitor-2.0.0-SNAPSHOT.jar
# 📦 EasyPerfMonitorStandalone/target/EasyPerfMonitorStandalone-2.0.0.jar
# 📦 EasyPrefMonitorBungee/target/BungeePerfMonitor-2.0.jar

🔧 Build Single Module

# EasyPerfMonitor only
cd EasyPerfMonitor && mvn clean package

# Standalone only
cd EasyPerfMonitorStandalone && mvn clean package

# BungeeCord only
cd EasyPrefMonitorBungee && mvn clean package

📋 Dependencies

Dependency	Version	Purpose
Spigot API	1.8.8-R0.1-SNAPSHOT	Server API
BungeeCord API	1.20-R0.1	Proxy API
PoloCloud SDK	3.0.0-pre.5-SNAPSHOT	Cloud integration
Jedis	3.9.0	Redis client
Gson	2.10.1	JSON parsing

🐛 Troubleshooting

❓ PoloCloud Not Detected

§7PoloCloud nicht gefunden, verwende Fallback-Konfiguration.

Solutions:

✅ Ensure PoloCloud is installed and running
✅ Check plugin load order (PoloCloud should load first)
✅ Verify polocloud.enabled: true in config.yml

❓ Redis Connection Failed

§cRedis connection failed! Running without Redis features.

Solutions:

✅ Check Redis is running: redis-cli ping → should return PONG
✅ Verify host and port in config.yml
✅ Check firewall settings
✅ Verify password if authentication is enabled

❓ Dashboard Not Accessible

Solutions:

✅ Check firewall allows port 8080/8081
✅ Verify web.host: "0.0.0.0" for external access
✅ Check logs for port conflicts
✅ Try http://localhost:8080 first for local testing

❓ High CPU Usage

Solutions:

✅ Increase monitoring.update-interval in config
✅ Disable subscribe-to-metrics if not needed
✅ Reduce max-history-points
✅ Lower web dashboard refresh rate

🏗️ Architecture

PerfMonitor/
│
├── 📁 EasyPerfMonitor/                    # Spigot/Paper Plugin
│   ├── PoloCloudHook.java                 # ☁️ PoloCloud detection
│   ├── EasyPerfMonitor.java               # 🎮 Main plugin class
│   ├── RedisManager.java                  # 🔴 Redis pub/sub
│   ├── WebFileHandler.java                # 🌐 HTTP server
│   ├── AsyncMonitor.java                  # 📊 Performance tracking
│   └── PerfCommand.java                   # ⌨️ Commands
│
├── 📁 EasyPerfMonitorStandalone/          # Standalone Module
│   ├── RedisManager.java                  # 🔴 Redis integration
│   └── PerfCommandStandalone.java         # ⌨️ Commands
│
└── 📁 EasyPrefMonitorBungee/              # BungeeCord Plugin
    ├── PoloCloudHook.java                 # ☁️ PoloCloud detection
    ├── BungeePerfMonitor.java             # 🎮 Main plugin class
    ├── BungeeWebHandler.java              # 🌐 HTTP server
    ├── DiscordWebhook.java                # 💬 Discord alerts
    └── ServerPerformanceData.java         # 📊 Data model

🤝 Contributing

Contributions are welcome! Here's how you can help:

Way	How
🐛 Report Bugs	Open an Issue
💡 Suggest Features	Open an Issue
🔧 Submit Code	Create a Pull Request
⭐ Star the Repo	Show your support!

📝 Pull Request Process

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m '✨ Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2024 PerfMonitor

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software...

👥 Credits

Authors: Sypherox, zgodsw

Built with:

⭐ If this project helped you, please consider giving it a star! ⭐

⬆ Back to Top

Name		Name	Last commit message	Last commit date
EasyPerfMonitor		EasyPerfMonitor
EasyPerfMonitorStandalone		EasyPerfMonitorStandalone
EasyPrefMonitorBungee		EasyPrefMonitorBungee
.gitignore		.gitignore
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

PerfMonitor

⚡ Modern Performance Monitoring for Minecraft Server Networks

📑 Table of Contents

✨ Features

🌐 Web Dashboard

☁️ PoloCloud Integration

🔴 Redis Support

🔗 BungeeCord Messaging

📈 Smart Metrics

💬 Discord Alerts

📦 Modules

🎯 Which Module Should I Use?

☁️ PoloCloud Integration

🔄 How It Works

📝 Configuration

🎯 Benefits

🚀 Quick Start

📋 Prerequisites

⚡ Installation

🎮 First Steps

⚙️ Configuration

📄 EasyPerfMonitor (Spigot/Paper)

📄 EasyPrefMonitorBungee (BungeeCord)

🎮 Commands

📊 Performance Output Example

📊 Dashboard

🖥️ Web Interface

📈 Available Metrics

🔧 Advanced Usage

🔌 API Integration

📡 Redis Data Format

🛠️ Building

📦 Build All Modules

🔧 Build Single Module

📋 Dependencies

🐛 Troubleshooting

🏗️ Architecture

🤝 Contributing

📝 Pull Request Process

📄 License

👥 Credits

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages