Automatic Lag Detective

What is Automatic Lag Detective?

Automatic Lag Detective (ALD) is not another TPS meter. It doesn't just tell you "the server is lagging" — it acts like an automatic investigator that watches your server 24/7, notices when something goes wrong, reconstructs what happened, and tells you why it happened in plain English, with real evidence to back it up.

When performance drops, ALD will:

• Detect the problem automatically, no manual checks required
• Investigate by correlating dozens of live metrics with what was happening on your server at that moment
• Diagnose one or more probable root causes, each with a confidence percentage
• Localize the problem to specific chunks/areas of the world whenever possible
• Explain the reasoning with actual collected evidence — never a guess dressed up as a fact
• Recommend specific, actionable fixes based on what was actually found

If ALD isn't confident enough in a diagnosis, it will honestly tell you "Root Cause: Unknown" instead of making something up. It never invents evidence.


⚙️ Requirements

• Paper 1.21.11 (or a Paper fork built against the same API version)
• Java 21 or newer
• No other plugins or dependencies required

Note: ALD is built specifically for Paper's API. It will not work on vanilla, Fabric, Forge or Bukkit/Spigot-only servers.


Installation

1. Stop your server.
2. Drop AutomaticLagDetective.jar into your /plugins folder.
3. Start your server. A config.yml will be generated automatically inside /plugins/AutomaticLagDetective/.
4. (Optional) Edit config.yml to your liking, then run /ald reload — no restart needed.

That's it. ALD starts learning your server's normal performance behavior immediately and needs no further setup to work.

Important: ALD needs a little time after startup to learn what "normal" looks like on your specific server (this is called the baseline). During the first few minutes after installation, some detections may be less accurate simply because it hasn't finished learning yet. This is expected and resolves itself automatically.


️ Commands

The base command is /ald. Running it with no arguments (as a player) opens the graphical dashboard.

Command	Description
/ald	Opens the graphical administration dashboard (players only)
/ald status	Shows a quick overall health snapshot: TPS, MSPT, heap usage, entity count, active incident
/ald diagnose	Runs an on-demand diagnosis using the current live metrics, even if no incident is currently active
/ald incidents	Lists the currently active incident (if any) and the most recent resolved ones
/ald incident <id>	Shows the full detail of a specific incident: evidence, timeline, affected chunks/players, recommendations
/ald chunks	Lists the busiest chunks currently being tracked, ranked by activity score
/ald chunk <world> <x> <z>	Shows detailed activity data for one specific chunk (entities, hoppers, redstone events, etc.)
/ald player <name>	Shows recent tracked actions for a player (block placements, chunk movement) relevant to performance correlation
/ald plugins	Lists installed plugins and the current approximate scheduler load
/ald reload	Reloads config.yml and restarts internal tasks without needing a server restart
/ald debug	Toggles verbose internal debug logging (useful when reporting an issue)
/ald gui	Opens the graphical administration dashboard directly

All commands support tab-completion, including live suggestions for online player names, world names and incident IDs.


Permissions

By default, all permissions are granted to server operators (OP) only. Give these to trusted staff via your permissions plugin (LuckPerms, PermissionsEx, etc.) as needed.

Permission	Grants access to
ald.admin	Grants every permission below at once
ald.use	Base access to the /ald command
ald.status	/ald status
ald.diagnose	/ald diagnose
ald.incidents	/ald incidents and /ald incident <id>
ald.chunks	/ald chunks and /ald chunk <world> <x> <z>
ald.player	/ald player <name>
ald.plugins	/ald plugins
ald.reload	/ald reload
ald.debug	/ald debug
ald.gui	Opening the graphical dashboard
ald.alerts	Receiving automatic in-chat alerts when an incident or a degrading trend is detected

️ Using the Dashboard (GUI)

Run /ald or /ald gui to open the dashboard. It's organized into a few screens:

• Main screen — current server health (TPS/MSPT/heap/entities), the active incident (if any), and shortcuts to the other screens
• Active Chunks — the busiest chunks on your server right now, ranked by an overall activity score, with a breakdown of entities/villagers/hoppers/redstone activity per chunk
• Incident History — a browsable list of the active incident plus recently resolved ones
• Incident Detail — click any incident to see: overview (severity, MSPT before/during/peak, duration, related players), every contributing root cause with its confidence %, the actual evidence collected for each one, and the specific recommendations generated for that incident

The GUI is read-only and completely safe to open on a live server — it never modifies gameplay, blocks, or items.


Automatic Alerts

Players/console with the ald.alerts permission automatically receive a chat message when:

• A new performance incident is detected
• ALD predicts a worsening trend before it becomes severe lag (e.g. "Villager pathfinding activity is up 320% over the last 5 minutes")

Alerts are throttled by a cooldown (configurable, default 60 seconds) so you won't get spammed during a prolonged incident.


How an Incident is Investigated

1. Detected — MSPT or TPS crosses a warning threshold
2. Investigating — ALD starts actively collecting evidence and correlating events
3. Diagnosed — one or more root causes are identified, each with its own confidence score and supporting evidence
4. Recovering — performance has returned to normal, ALD is confirming it's stable before closing the case
5. Resolved — the incident is closed, a full report is saved to disk, and it appears in your incident history

ALD can identify multiple simultaneous causes for the same incident (for example: 43% villager pathfinding, 27% plugin task pressure, 18% chunk loading, 8% GC pressure) rather than forcing everything into a single explanation.



Root Cause Categories

ALD's diagnostic engine checks for the following categories of problems. It only reports a category if it actually finds meaningful evidence for it:

• Entity Overload
• Villager / Pathfinding Overload
• Item Entity Overload (uncollected drops)
• Hopper Overload
• Block Entity Overload (chests, furnaces, etc.)
• Redstone Activity
• Chunk Loading Pressure
• Chunk Generation Pressure
• Plugin/Scheduler Task Pressure
• CPU Saturation
• Garbage Collection Pressure
• Memory Pressure
• Player Concentration (many players active in one small area — often just normal load, not a problem)
• Unknown/Other (shown honestly when the evidence isn't strong enough to name a specific cause)

About Player Correlation

ALD may sometimes note that a player's recent actions (e.g. placing 40 hoppers, or exploring into a new area) correlate with a performance change that followed shortly after. This is presented as evidence, not an accusation — ALD uses neutral language like "Related activity detected" and never states that a player definitively caused an incident. Use this information as a starting point for your own investigation, not as a verdict.


Baseline Learning (Why numbers may look different from another server)

ALD does not use the same fixed limits for every server. It learns what's normal for your specific server over time — a large modded server with 10,000 entities and dozens of players is not automatically flagged as unhealthy just because a small vanilla server would be. Detections become more accurate the longer ALD runs, as it builds a better picture of your server's normal behavior.


️ Configuration Overview (config.yml)

The configuration file is extensively commented and organized into clear sections. After any change, run /ald reload to apply it — no restart required. Here's what each section controls:

• performance — how often ALD samples the server and how much scanning work it does per cycle (lower values = more accurate but slightly more overhead)
• baseline — how ALD learns "normal" behavior for your server, and how big a deviation counts as a warning/critical signal
• detection — the MSPT/TPS thresholds that open and close incidents, plus cooldown timers
• analysis — sensitivity ("weight") of each root-cause analyzer; raise a value to make ALD more sensitive to that specific category
• root-cause — minimum confidence required before a cause is reported, and how many simultaneous causes can be shown per incident
• timeline — how much event history ALD keeps in memory for reconstructing incidents
• entities — which mob types are treated as "pathfinding-capable" for the villager/pathfinding analyzer
• chunks — how chunks are grouped into regions, and the concentration threshold used to call something a "hotspot"
• players — the time window used to correlate a player's actions with a later performance change
• plugins — sampling interval for the approximate scheduler/plugin load metric
• incidents — how many resolved incidents are kept in memory/history, and how long stable performance must hold before an incident is auto-resolved
• recommendations — maximum number of recommendations generated per incident
• alerts — whether/how automatic chat alerts are sent, and their cooldown
• gui — refresh behavior of the dashboard
• storage — whether resolved incidents are saved to disk, and where
• advanced — debug logging, trend detection window/sensitivity, and internal safety toggles

Tip: If you're unsure what to change, leave the config as-is — the defaults are tuned to work well on most servers out of the box.


Incident Reports on Disk

When storage is enabled (default), every resolved incident is saved as a readable YAML report inside:

Each file contains the full diagnosis, evidence, timeline and recommendations for that incident, so you can review past lag spikes even after a server restart.


⚡ Performance Impact

ALD is designed to never become a source of lag itself:

• It never scans the entire world at once — chunk data is scanned incrementally in small batches, cycling through loaded chunks over time
• Metrics are sampled on a configurable interval rather than every tick
• All heavy work runs safely on the main thread only where required by Minecraft, with lightweight event listeners elsewhere
• No memory leaks, no orphaned threads — all internal tasks are properly stopped when the plugin reloads or the server shuts down

On a typical server you will not notice ALD running at all.


❓ FAQ

Q: Does ALD automatically fix lag?
No. ALD only investigates and diagnoses — it does not kill entities, remove blocks, or change gameplay in any way. It gives you the information needed to fix the problem yourself.

Q: Will it work with plugins like ClearLag, Spark, or EssentialsX?
Yes, ALD does not conflict with other performance or utility plugins. It reads data through standard server APIs only.

Q: Why does it say "Root Cause: Unknown"?
ALD only reports a cause when it has real, sufficient evidence for it. If the evidence collected doesn't clearly point to a specific cause, it will honestly say so instead of guessing.

Q: I just installed it and it's not detecting anything useful yet.
Give it some time — the adaptive baseline needs to observe your server for a while before its detections become fully accurate.

Q: Does it support Folia?
No, ALD currently targets Paper 1.21.11.