ServerSense

Advanced performance monitoring for Bukkit/Spigot/Paper servers with health analysis, plugin profiling, automatic mitigations, and Discord alerts featuring visual analytics (PNG canvas).

Highlights

• Collects global metrics (TPS, memory, entities, packets) and computes health and predictions.
• Profiles plugins (CPU%, listeners, approximate memory) and ranks impact.
• Detects “Can’t keep up”, memory leaks, and entity anomalies with suggested actions.
• Auto-disables high-impact plugins using double confirmation and auto re-enable after cooldown.
• Sends Discord alerts with image analytics, rate limiting, and per-topic webhooks.
• Enhanced TPS and plugin reports, plus an in-game GUI.

Requirements

• Paper/Spigot/Bukkit 1.20+
• Java 17+

Installation

1. Place the jar in your server’s plugins/ folder.
2. Start the server to generate plugins/ServerSense/config.yml.
3. Set license.key in the config and restart.

Commands

• serversense (aliases: ss, ssense)
  • Commands:
• /ss health: Shows a concise server health summary with current Health Score, TPS, memory usage, thresholds, and actionable recommendations.
• /ss plugin <name>: Analyzes the specified plugin’s impact (CPU ms/%, allocation MB/s, listener count, approx memory footprint, GC attribution).
• /ss analyze: Live view of top plugins by impact (CPU%, allocation rate, listeners) when profiling is active.
• /ss export: Exports current diagnostics to a JSON file in the ServerSense data folder for offline analysis/support.
• /ss reload: Reloads config.yml and applies runtime updates (config validation, whitelist reload, webhook routes refresh, cache invalidation). Requires serversense.admin.
• /ss reset: Resets the learned performance baseline and restarts the learning phase to recalibrate health calculations.
• /ss alert: Toggles the caller’s in‑game alert subscription. Requires serversense.view.
• /ss help: Displays available subcommands with usage hints.
• /ss gui|menu|admin: Opens the in‑game GUI for the player. Requires serversense.view.
• /pl (alias plugins): Enhanced plugin list with diagnostics (top impact, listeners, approximate resources).
• stps: Enhanced TPS report and breakdown (TPS, memory %, entity/chunk counts, entity categories, predictions, hot chunks).

Permissions

• serversense.admin: full access, required for reload and administrative tasks.
• serversense.view: view status and open the GUI.
• serversense.view.basic / serversense.view.detailed / serversense.view.advanced: control visibility of breakdowns and predictions.

Discord Alerts & Webhooks

• Configure alerts.webhooks.* for per-topic routes: main, prediction, plugin-disable, gc, memory-leak.
• Rate limit with alerts.max-alerts-per-minute; fingerprint deduplication prevents spam.
• All alerts ship an analytics PNG image with a short description.
• Legacy alerts.discord-webhook is supported for the main route.
• Treat your config file as sensitive when webhooks are configured.

Auto-Disabler

• Strike-based logic plus double confirmation reduces false positives.
• Automatically re-enables disabled plugins after cooldown-minutes.
• Can perform immediate disable for suspected OutOfMemoryError scenarios.

Full Configuration Guide (config.yml)

license

• license.key: Your license key.
  • Empty: the plugin disables itself and logs a configuration hint.
  • Invalid/not found: the plugin disables itself and logs the reason.

system

• learning-phase-hours (int > 0): Learning phase duration used for baselines.
  • <= 0: warning; falls back to a safe default (2 hours).
• global-metrics-interval-seconds (int > 0): Sampling interval for global metrics.
  • <= 0: configuration error; metrics collection requires a positive interval.
• level-2-threshold-health-score (0–100): Health score threshold to activate Level 2 analysis.
  • If set lower than level-3-threshold-health-score, a warning is logged (L2 should be above L3).
  • If health < threshold: L2 analysis and profiling become active.
• level-2-max-duration-minutes (int > 0): Maximum duration for Level 2 analysis.
  • <= 0: configuration error.
• level-3-threshold-health-score (0–100): Critical threshold to activate forensic Level 3 analysis.
  • If health < threshold: Level 3 forensic mode activates (more intensive analysis).
• level-3-max-duration-minutes (int > 0): Maximum duration for Level 3.
  • <= 0: configuration error.
• max-tracked-players (int > 0): Max number of players tracked in packet analysis.
  • Higher values cover more players but may increase overhead.

command-overrides

• override-pl (true/false): If true, replaces the vanilla /pl with ServerSense output.
• override-tps (true/false): If true, replaces the vanilla TPS command with the enhanced version.
• prevent-vanilla-pl (true/false): If true, blocks vanilla /pl.
• prevent-vanilla-tps (true/false): If true, blocks vanilla tps.

plugin-diagnostics

• enable (true/false): Enables plugin diagnostics.
• cpu-calculation (true/false): Shows estimated CPU time per plugin.
• ram-calculation (true/false): Shows approximate memory footprint per plugin.
• tps-impact-calc (true/false): Includes estimated TPS impact.
• show-top-n-plugins (int > 0): Number of top plugins to display.
  • If set above actual count, the list shows available entries.
• group-rest-as (string): Label used to group the remaining plugins.
• cpu-sample-rate (0–1): Sampling ratio; lower values reduce overhead, higher values increase accuracy.
• approximate-values (true/false): If true, displays approximate metrics rather than exact ones.

tps-breakdown

• enable (true/false): Enables TPS breakdown reporting.
• show-plugin-breakdown (true/false): Shows per-plugin contribution.
• show-entity-breakdown (true/false): Shows entity categories (hostile, passive, items, projectiles).
• show-redstone-load (true/false): Shows redstone load; useful for farms-heavy servers.
• show-chunk-load (true/false): Shows hot chunks; if false, chunk list is hidden.
• show-top-culprits (true/false): Lists top culprits impacting TPS.
• show-prediction (true/false): Adds a prediction section.
• forecast-minutes (int > 0): Prediction window; larger windows increase uncertainty.

level-1-checks

• tps-monitoring (true/false): Monitors TPS and alerts if it drops.
• memory-monitoring (true/false): Monitors memory usage and GC pauses.
• packet-rate (true/false): Estimates packet rate; ProtocolLib recommended for best results.
• entity-count (true/false): Monitors total entities.
• chunk-count (true/false): Counts loaded chunks; disable if world scale makes it expensive.
• gc-monitoring (true/false): Monitors GC pauses and alerts when over gc-pause-warning-ms.

level-2-checks

• enable (true/false): Enables Level 2 analysis when the threshold is crossed.
• region-analysis (true/false): Analyzes hot regions; can be more expensive.
• listener-profiling (true/false): Profiles slow event listeners.
• packet-attribution (true/false): Attributes packet impact; ProtocolLib improves accuracy.
• memory-leak-detection (true/false): Detects memory leak trends.
• entity-anomaly-detection (true/false): Detects entity anomalies per chunk/region.

listener-profiler

• sample-rate (0–1): Fraction of events sampled; higher = more accurate, more overhead.
• min-sample-rate (0–1): Lower dynamic bound for sampling.
• max-sample-rate (0–1): Upper dynamic bound for sampling.
• slow-threshold-ms (double): Slow event threshold; raising reduces alerts.

alerts

• health-score-warning (0–100): Warning threshold; health <= value triggers warning.
• health-score-critical (0–100): Critical threshold; health <= value triggers critical alert.
• gc-pause-warning-ms (int > 0): GC pause threshold for warnings.
• memory-leak-rate-mb-per-hour (double > 0): Leak rate that triggers alerts; higher sensitivity sends more alerts.
• player-upgrade-threshold (int >= 0): Player count threshold for upgrade suggestions.
• discord-webhook (string): Legacy webhook for the main route.
• send-hourly-report (true/false): If true, sends an hourly report.
• send-alert-on-critical (true/false): If true, sends an alert when reaching health-score-critical.
• max-alerts-per-minute (int >= 0): 0 disables rate limiting; higher values allow more alerts per minute.
• verbose-debug (true/false): If true, logs more diagnostic details.
• ingame-enable (true/false): If true, in-game messages to players with serversense.view who subscribed.
• webhooks.* (HTTPS Discord URLs): Per-route webhooks.
  • Invalid/empty URL: route is disabled and a warning is logged.

messages

• tps-player-upgrade-notice: Text for high player count notice; supports {players} placeholder.
• tps-player-load-ok: Text for normal player load.

auto-disabler

• enable (true/false): Enables automatic disable for high-impact plugins.
• cpu-threshold-ms (double > 0): CPU ms threshold to count impact; higher = less aggressive.
• min-active-seconds (int >= 5): Minimum active time of L2 before evaluation.
• cooldown-minutes (int > 0): Time after which a disabled plugin is automatically re-enabled.
• never-disable (list): Plugin names that are never disabled.
• stps-cpu-threshold-ms (double): Threshold for severe CPU cases.
• stps-cpu-ratio (double): Severe CPU ratio compared to baseline.
• stps-cpu-percent-threshold (double 0–100): CPU percent threshold.
• stps-cpu-percent-ratio (double): Ratio by CPU percent.
  • Lower thresholds increase aggressiveness; higher thresholds reduce interventions.

whitelists

• enable (true/false): Enables whitelisting.
• chunks (map): Expected high-activity areas; reduces false positives.
• plugins (map): Plugins with expected entity behavior (e.g., NPCs).

optimization

• precalculate-interval-seconds (int > 0): Interval for pre-calculated cache refresh.
• cache-pl-output (true/false): Caches /pl output for performance.
• cache-tps-output (true/false): Caches /stps output.
• max-plugins-show (int > 0): Max number of “top” plugins shown.
• enable-entity-breakdown (true/false): Enables entity breakdown.
• enable-top-chunks (true/false): Shows hot chunks.
• entity-breakdown-async (true/false): Runs breakdown asynchronously; reduces tick impact.

entity-mitigation

• enable (true/false): Enables entity mitigation actions.
• total-entity-threshold (int > 0): Total entity threshold to intervene.
• per-chunk-entity-threshold (int > 0): Per-chunk threshold.
• anomaly-per-chunk-threshold (int > 0): Per-chunk anomaly threshold; lower = more sensitive.
• anomaly-tps-threshold (double): If TPS < value and anomalies exist, more aggressive actions apply.
• max-hotspots-per-cycle (int > 0): Max hotspots to treat per cycle.
• max-remove-per-chunk (int > 0): Max entities removed per chunk.
• region-radius-chunks (int > 0): Region radius in chunks.
• region-entity-threshold (int > 0): Region entity threshold.
• max-remove-per-region (int > 0): Max removed per region.
• insta-chunk-entity-threshold (int > 0): Instant per-chunk threshold for quick measures.
• insta-region-entity-threshold (int > 0): Instant per-region threshold.
• cooldown-millis (int > 0): Cooldown time between mitigation cycles.

redstone-mitigation

• enable (true/false): Enables redstone load mitigation.
• tile-entity-threshold-per-chunk (int > 0): Tile entity per-chunk threshold to trigger mitigation.
• duration-seconds (int > 0): Mitigation duration.

crash-prevention

• enable (true/false): Enables crash prevention logic.
• shutdown-on-severe-leak (true/false): If true, shuts down when a severe leak is detected.
• severe-leak-hours-until-crash (double > 0): If estimated hours until crash < value, considered severe.
• severe-memory-percent (double 0–100): If memory percent > value and severe, actions apply.

Best Practices

• Tune auto-disabler thresholds conservatively at first, then refine based on observations.
• Use max-alerts-per-minute to prevent spam while retaining canvas-based alerts.
• Install ProtocolLib to improve packet-based checks and attribution if needed.

Support

• Enable alerts.verbose-debug=true to see detailed diagnostic logs (webhook warnings, rate-limit skips).
• In critical memory cases, the system will attempt to mitigate or alert early (leak/GC detection).