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

• 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

Automatic Lag Diagnosis

• Performance Drop Detection — automatically triggers when TPS drops or MSPT spikes
• Full Server Snapshots — captures chunks, entities, memory, and player locations at the moment of the drop
• 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

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 all settings without touching files
• AntiCheat GUI — status overview, whitelist info, XRay settings
• Multi-page navigation, color-coded items, intuitive design

AntiCheat Module (Beta)

• XRay Detection — frequency analysis, ore/stone ratio, per-ore thresholds, Y-level pattern analysis
• Restricted World Zones — instant alerts when ores are mined in protected worlds
• Movement Checks — speed, fly, and teleport detection with movement type awareness
• Smart False-Positive Reduction — lag compensation (sqrt-scaled), knockback immunity, potion effects, vehicle awareness
• Bundled Alerts — 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 all 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

• 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
• Auto Database Cleanup — configurable retention (default: 30 days)
• Multi-Language — English & German, easily extensible

Commands

Permissions

Configuration Highlights

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

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:
  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: 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"]

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

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

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

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

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.