PerformanceAnalyzer

PerformanceAnalyzer gives you clear visibility into how your server is performing live and over time. With database-backed statistics, an in-game GUI, optional Discord alerts, and a helper-level AntiCheat/X-Ray module, it’s a handy toolkit for anyone.

383

Quick challenge

How far can you run before the mobs catch you?

PerformanceAnalyzer

The all-in-one server monitoring, lag diagnosis & AntiCheat plugin for Paper 1.21.x

Monitor your server in real-time, find the source of lag spikes in seconds, detect cheaters, and keep your players happy — all from a single plugin.

---

Why PerformanceAnalyzer?

Most monitoring plugins tell you *that* your server is lagging. PerformanceAnalyzer tells you why.

When a TPS drop occurs, the plugin automatically captures a full snapshot of your server state — loaded chunks, entity counts, player activity, suspect plugins — so you can diagnose the problem instantly instead of guessing.

---

Key Features

Real-Time Performance Monitoring

- Database Logging tracking with historical data and ASCII sparklines - Database Logging for highly accurate TPS (10s/1m/5m), MSPT (avg/p95/max), and CPU data - Database Logging for packet analysis and flood detection - Database Logging (SQLite or MySQL) with async batch writes via HikariCP

Automatic Lag Diagnosis

- Chunk Thrashing Detection — automatically triggers when TPS drops or MSPT spikes - Chunk Thrashing Detection — captures chunks, entities, memory, and player locations at the moment of the drop - Chunk Thrashing Detection — identifies the players and plugins most likely responsible - Chunk Thrashing Detection — finds chunks overloaded with tile entities or redstone - Chunk Thrashing Detection — spots chunks that load/unload too frequently

Interactive GUI System

- AntiCheat GUI — live TPS, MSPT, heap with auto-refresh - AntiCheat GUI — top 5 active players and suspect plugins with risk scores - AntiCheat GUI — browse up to 21 recent drops, click for detailed reports - AntiCheat GUI — toggle all settings without touching files - AntiCheat GUI — status overview, whitelist info, XRay settings - Multi-page navigation, color-coded items, intuitive design

AntiCheat Module (Beta)

- Whitelist System — frequency analysis, ore/stone ratio, per-ore thresholds, Y-level pattern analysis - Whitelist System — instant alerts when ores are mined in protected worlds - Whitelist System — speed, fly, and teleport detection with movement type awareness - Whitelist System — lag compensation (sqrt-scaled), knockback immunity, potion effects, vehicle awareness - Whitelist System — one summary in chat, full details via command - Whitelist System — per-player UUIDs and LuckPerms groups

> Note: The AntiCheat module is experimental. For production use, we recommend dedicated plugins like Matrix, Vulcan, or Spartan.

Silent Mode / Streamer Mode (New in v2.3.1)

- `/perfsilent` — mute Persistent alert notifications in chat - `/perfsilent xray` / `movement` / `performance` — mute individual categories - `/perfsilent list` — view your current preferences - Persistent across server restarts - Perfect for streamers, builders, or admins who don't need constant notifications

Discord Webhook Integration

- Automatic notifications for TPS drops, high MSPT, heap warnings, packet floods, and AntiCheat alerts - Color-coded embeds per alert type - Configurable: choose exactly which events get reported - Async HTTP requests — zero performance impact

Auto Entity Cleaner

- Priority-based removal: items > projectiles > monsters > animals - Protects named entities, tamed animals, villagers, boss mobs - Per-world and per-chunk limits - Dry-run mode for safe testing before enabling

Additional Tools

- Multi-Language (`/worldstats`) — entities, chunks, density, trend analysis per world - Multi-Language (`/entitystats`) — breakdown by category, hotspot detection - Multi-Language (`/chunkstats`) — load tracking, problematic chunks, thrashing - Multi-Language — JSON endpoints for Grafana/Prometheus dashboards with API key auth - Multi-Language — configurable retention (default: 30 days) - Multi-Language — English & German, easily extensible

---

Commands

| Command | Description | Permission | |---------|-------------|------------| | `/perfstatus` | Live TPS, MSPT, heap data | `performance.status` | | `/perfhistory [min]` | Historical MSPT sparkline & stats | `performance.history` | | `/perfgui` | Open the interactive GUI | `performance.gui` | | `/perfreload` | Reload plugin configuration | `performance.admin` | | `/perfsilent [type]` | Toggle alert notifications | `performance.admin` | | `/perfdrops [#]` | View/analyze performance drops | `performance.admin` | | `/worldstats [world]` | Per-world statistics | `performance.admin` | | `/entitystats [world]` | Entity analysis & hotspots | `performance.admin` | | `/chunkstats [sub]` | Chunk load tracking & problems | `performance.admin` | | `/xrayalerts [player]` | XRay suspicion alerts | `performance.admin` | | `/movealerts [player]` | Movement suspicion alerts | `performance.admin` | | `/xrayores [sub]` | Manage XRay ore exclusions | `performance.anticheat.manage` | | `/acwhitelist [sub]` | Manage AntiCheat whitelist | `performance.anticheat.manage` |

---

Permissions

| Permission | Description | Default | |------------|-------------|---------| | `performance.status` | Use `/perfstatus` | Everyone | | `performance.history` | Use `/perfhistory` | Everyone | | `performance.gui` | Use `/perfgui` | Everyone | | `performance.admin` | Admin commands, alert notifications | OP | | `performance.anticheat.manage` | Manage whitelist & ore exclusions | OP | | `performance.anticheat.bypass` | Bypass all AntiCheat checks | false |

---

Configuration Highlights

Database (SQLite or MySQL)

```yaml database: type: sqlite # or 'mysql' sqlite_file: "plugins/PerformanceAnalyzer/perf.db" retention_days: 30 # Auto-cleanup (0 = disabled) pool: max_pool_size: 10 minimum_idle: 2 ```

Performance Thresholds

```yaml thresholds: mspt: 50.0 # MSPT warning (ms) heap_usage_percent: 80.0 # Heap warning (%) tps_drop: 19.0 # TPS drop warning packet_flood_per_tick: 1000.0 # Packet flood detection ```

Lag Analysis Thresholds

All thresholds are adjustable for your hardware:

```yaml lag_analysis: player_tracking: true plugin_analysis: true chunk_analysis_timeout_ms: 5000

Chunk thresholds (Standard | Powerful | Weak)

chunk_tile_entities_threshold: 10 # 10 | 20-30 | 5-8 chunk_redstone_threshold: 30 # 30 | 50-100 | 15-20 chunk_entity_warning: 50 # 50 | 80-100 | 30-40 chunk_entity_critical: 100 # 100 | 150-200 | 60-80

World thresholds

world_entity_warning: 5000 world_entity_critical: 10000 ```

AntiCheat — XRay Detection

```yaml anticheat: xray_detection: true xray_timewindow_seconds: 60 xray_stone_ore_ratio: 0.10 # Normal: 2-5%, Suspicious: >10% ops_bypass: false xray_excluded_ores: [] # e.g. ["COAL_ORE", "IRON_ORE"]

xray_thresholds: # Per-ore (rare = lower threshold) coal: 20 iron: 15 diamond: 6 emerald: 4 ancient_debris: 3

Restricted zones: instant alerts in specific worlds

restricted_worlds: [] # e.g. ["mining_world"] restricted_world_ores: [] # e.g. ["DIAMOND_ORE", "EMERALD_ORE"] ```

Deepslate variants are automatically included.

AntiCheat — Movement Detection

```yaml anticheat: movement_checks: true speed_detection: true fly_detection: true teleport_detection: true

speed_thresholds: walk: 0.5 sprint: 1.0 fly: 1.5 vertical: 3.5 teleport: 15.0 violations_before_alert: 5 fly_violations_before_alert: 10 ```

Automatically accounts for: potions, soul speed, vehicles, elytra, riptide, swimming, climbing, knockback, and player ping.

Discord Webhook

```yaml discord: enabled: false webhook_url: "" alert_types: high_mspt: true tps_drop: true high_heap: true packet_flood: true anticheat: true ```

REST API

```yaml api: enabled: false port: 8080 key: "changeme" # IMPORTANT: Set a secure key! ```

Endpoints: `/api/health`, `/api/metrics`, `/api/worlds`, `/api/trends` Authentication: `Authorization: Bearer <key>`

Auto Entity Cleaner

```yaml entity_cleaner: enabled: false interval_seconds: 300 world_limit: 5000 chunk_limit: 100 dry_run: true # Test mode (logs only, no removal) protect_villagers: true protect_item_frames: true blacklist: ["ENDER_DRAGON", "WITHER", "WARDEN"] ```

---

Language Support

English and German included. Language files are in `plugins/PerformanceAnalyzer/lang/` and fully customizable.

Adding a new language: 1. Copy `en.yml` to your language code (e.g. `fr.yml`) 2. Translate all messages 3. Set `language: fr` in `config.yml` 4. Run `/perfreload`

---

Optional Dependencies

| Plugin | Benefit | |--------|---------| | spark | Accurate TPS (10s/1m/5m), MSPT (avg/p95/max), CPU monitoring | | ProtocolLib | Packet analysis & flood detection | | LuckPerms | Group-based AntiCheat whitelist |

All integrations are optional — the plugin works fully standalone.

---

Requirements

- Paper 1.21.4 – 1.21.x - Paper 1.21.4 – 1.21.x - Thread-safe, async operations, minimal performance overhead

---

Config Auto-Migration

When updating, your existing config is never overwritten. New settings are automatically added with sensible defaults. Just replace the JAR and restart.

---