PerformanceAnalyzer

Why PerformanceAnalyzer?

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

When a TPS drop or MSPT spike 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.

⚡ New in v3.0.0

• AntiCheat is now its own plugin. PerformanceAnalyzer is now a focused, pure performance monitor. The XRay/Movement detection lives on in the standalone BSAntiCheat plugin — install it alongside PerformanceAnalyzer and the GUI will link the two together automatically.
• Per-second drop detection — performance drops are now sampled every second (decoupled from the database logging interval), so short-lived spikes are no longer missed.
• REST API is live — JSON endpoints for Grafana/Prometheus dashboards.
• Developer API — other plugins can read live TPS/MSPT/heap/entity data.

---

Key Features

Real-Time Performance Monitoring

• TPS, MSPT & Heap tracking with historical data and ASCII sparklines
• Spark Integration for highly accurate TPS (10s/1m/5m), MSPT (avg/p95/max), and CPU data
• ProtocolLib Integration for packet analysis and flood detection
• Database Logging (SQLite or MySQL) with async batch writes via HikariCP
• Fallback File Logging — if the database goes down, metrics are written to a file instead of being lost

Automatic Lag Diagnosis

• Performance Drop Detection — triggers automatically when TPS drops or MSPT spikes, sampled every second
• Full Server Snapshots — captures chunks, entities, memory, and player locations at the moment of the drop
• Accurate Low/High Tracking — reports the actual worst TPS/MSPT seen during the drop window
• Lag Source Analysis — identifies the players and plugins most likely responsible
• Problematic Chunk Detection — finds chunks overloaded with tile entities or redstone
• Chunk Thrashing Detection — spots chunks that load/unload too frequently
• Throttled & quiet — the expensive deep analysis is rate-limited and stays out of the console unless debug mode is on, so the diagnostics never make the lag worse

Interactive GUI System

• Performance Dashboard — live TPS, MSPT, heap with auto-refresh
• Lag Analysis Page — top 5 active players and suspect plugins with risk scores
• Performance Drops Page — browse up to 21 recent drops, click for detailed reports
• Config GUI — toggle settings without touching files
• Companion detection — shows BSAntiCheat status when the AntiCheat plugin is installed
• Multi-page navigation, color-coded items, intuitive design

Silent Mode / Streamer Mode

• /perfsilent — mute all alert notifications in chat
• /perfsilent performance — mute just the performance alert category
• /perfsilent list — view your current preferences
• /perfsilent reset — receive all alerts again
• 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, and packet floods
• Color-coded embeds per alert type
• Configurable: choose exactly which events get reported
• Async, rate-limited HTTP requests — zero performance impact
• SSRF-protected: only valid Discord webhook URLs are accepted

Auto Entity Cleaner

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

Additional Tools

• World Statistics (/worldstats) — entities, chunks, density, trend analysis per world
• Entity Analysis (/entitystats) — breakdown by category, hotspot detection
• Chunk Statistics (/chunkstats) — load tracking, problematic chunks, thrashing
• REST API — JSON endpoints for Grafana/Prometheus dashboards with API key auth
• Developer API — PerformanceAPI for other plugins to read live metrics
• Auto Database Cleanup — 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 (streamer mode)	performance.admin
/perfdrops [#]	View/analyze performance drops	performance.admin
/worldstats [world]	Per-world statistics (alias /ws)	performance.admin
/entitystats [world]	Entity analysis & hotspots (alias /es)	performance.admin
/chunkstats [sub]	Chunk load tracking & problems (alias /cs)	performance.admin

---

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.silent	Use silent mode to mute alerts	OP

---

Configuration Highlights

Database (SQLite or MySQL)

database:
  type: sqlite                    # or 'mysql'
  sqlite_file: "plugins/PerformanceAnalyzer/perf.db"
  retention_days: 30              # Auto-cleanup (0 = disabled)
  fallback_file_logging: true     # Log to file if the DB is unavailable
  fallback_log_file: "plugins/PerformanceAnalyzer/fallback.log"
  pool:
    max_pool_size: 10
    minimum_idle: 2

Performance Thresholds

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:

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

Discord Webhook

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

REST API

api:
  enabled: false
  port: 8080
  key: "changeme"    # IMPORTANT: Set a secure key! The server won't start otherwise.

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

Auto Entity Cleaner

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"]
  world_whitelist: []            # Worlds that are never cleaned

---

Developer API

Other plugins can read live performance data directly:

PerformanceAPI api = (PerformanceAPI) Bukkit.getPluginManager().getPlugin("PerformanceAnalyzer");
double tps = api.getCurrentTPS();
double mspt = api.getCurrentMSPT();
double heap = api.getHeapUsagePercent();
int entities = api.getTotalEntityCount();

---

Language Support

English and German are included. Language files live in plugins/PerformanceAnalyzer/lang/ and are 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

---

Looking for AntiCheat?

As of v3.0.0, the XRay and Movement detection has moved into its own dedicated plugin: BSAntiCheat. Install both side by side — PerformanceAnalyzer handles performance and lag diagnosis, BSAntiCheat handles cheat detection, and the GUI links them together.

---

Optional Dependencies

Plugin	Benefit
spark	Accurate TPS (10s/1m/5m), MSPT (avg/p95/max), CPU monitoring
ProtocolLib	Packet analysis & flood detection
BSAntiCheat	Companion AntiCheat plugin (XRay & movement detection)

All integrations are optional — the plugin works fully standalone.

---

Requirements

• Java 21
• 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.

---

Special Thanks

To ELITEK3V for testing.