LagTrace

LagTrace

Find out what lagged your server, even when nobody was watching.

LagTrace runs quietly in the background. When your server's tick time goes over a threshold, it takes a snapshot of where the load was: the heaviest chunks, what was in them, and who was nearby. Come back the next morning, run /lagtrace report, and click straight to the chunk that caused the 3 a.m. lag spike.

Zero setup. No dependencies. Paper-based servers only.

Not a profiler. LagTrace doesn't replace Spark. Spark tells you which code is slow; LagTrace tells you which chunk, farm or contraption was behind it, and keeps a history so you can find it after the fact. They work well together.

---

Features

• Always-on lag detection. Checks the server's average tick time (MSPT) every second and records an incident when it crosses your threshold.
• Chunk hotspots. Each incident lists the heaviest chunks, scored by entities, tile entities (hoppers, chests, furnaces…) and redstone activity.
• Redstone tracking. Catches redstone clocks, observer chains and piston contraptions by counting power changes and piston moves per chunk.
• The details that matter. The top entity types, tile types and redstone components in each hotspot, plus the players who were nearby.
• Clickable alerts. Admins online get a chat alert with [Teleport] and [Details] buttons.
• Incident history. Incidents are saved to disk and survive restarts. Browse them with /lagtrace report.
• Live scan. /lagtrace chunks shows the heaviest chunks right now, without waiting for lag.
• Safe by design. The scan usually takes a few milliseconds. If it ever runs slow, LagTrace automatically backs off so the monitor never adds to the lag. All file writes happen off the main thread.

Example

LagTrace » Lag detected #463: 347.5 MSPT, TPS 15.6
Worst: world 31, 31 (block 504, 504): 2745 entities, 3 tiles, 40 redstone/s [Teleport] [Details]

#1 world chunk 31, 31 (block 504, 504) 2004 entities, 3 tiles, 40 redstone/s [Teleport]
   cow 2000, item 4 | moving_piston 2, spawner 1 | observer 230, piston 230, redstone_wire 230 | near: Steve

Requirements

• Paper 1.21.11 or newer, or a Paper fork such as Purpur or Pufferfish.
• Java 21 or newer (whatever your Paper version already requires; Paper 26.x needs Java 25).

Tested on: Paper 1.21.11, 26.1.2, 26.2 and 26.3. The same jar works on all of them.

• Spigot and CraftBukkit are not supported. LagTrace disables itself with a clear message on them.
• Folia is not supported yet.

Installation

1. Drop LagTrace-<version>.jar into your plugins/ folder.
2. Restart the server.
3. That's it. plugins/LagTrace/config.yml is created with sensible defaults.

LagTrace ignores lag for the first 2 minutes after startup, because world loading is always slow.

Commands

The root command is /lagtrace, alias /lt.

Command	What it does	Permission
/lagtrace status	Current TPS and MSPT, incident count, last incident, current cooldown	lagtrace.use
/lagtrace report	The last 5 incidents. Click one for details	lagtrace.report
/lagtrace report last <count>	The last count incidents (up to 50)	lagtrace.report
/lagtrace report <id>	Full detail of one incident, with every hotspot	lagtrace.report
/lagtrace chunks [world]	Live scan of the heaviest chunks right now (once per 10 s)	lagtrace.chunks
/lagtrace tp <id> [n]	Teleport to hotspot n (default 1) of an incident. Players only	lagtrace.tp
/lagtrace snapshot	Record an incident now, ignoring threshold and cooldown	lagtrace.admin
/lagtrace clear confirm	Delete all stored incidents	lagtrace.admin
/lagtrace reload	Reload config.yml. A broken file is rejected and the old settings stay	lagtrace.admin

Permissions

All permissions default to op.

Permission	Allows
lagtrace.*	Everything below
lagtrace.use	/lagtrace status
lagtrace.report	Viewing incidents
lagtrace.chunks	Live chunk scans
lagtrace.tp	Teleporting to hotspots
lagtrace.alert	Receiving lag alerts in chat
lagtrace.admin	snapshot, clear and reload

Configuration

plugins/LagTrace/config.yml. Invalid values are reset to their default and the key is named in the console. Apply changes with /lagtrace reload.

Key	Default	Meaning
mspt-threshold	80	Average MSPT that counts as an incident. 50 MSPT is the limit for a steady 20 TPS
sample-interval-ticks	20	How often MSPT is checked (20 ticks = 1 second)
cooldown-seconds	60	Minimum gap between two incidents. Alerts use the same cooldown
startup-grace-seconds	120	Ignore lag this long after startup
top-chunks	5	Hotspots stored per incident
tile-weight	2	How much one tile entity counts in a chunk's score, relative to one entity
redstone-weight	1	How much one redstone event per second counts in the score. 0 ignores redstone
nearby-player-radius	128	Players within this many blocks of a hotspot are listed
max-scan-ms	50	If a scan takes longer than this, the cooldown doubles (up to 10×)
max-log-entries	200	Incidents kept in memory and on disk
alert-ops	true	Send chat alerts to players with lagtrace.alert
world-blacklist	[]	Worlds that are never scanned, e.g. [minigame_lobby]

Chunk score = entities + tile entities × tile-weight + redstone events per second × redstone-weight.

How it works

• Detection: every sample-interval-ticks, LagTrace reads Paper's recent average tick time. If it's at or above mspt-threshold, the startup grace is over and the cooldown has passed, it takes a snapshot.
• Snapshot: one pass over each world's entities, grouped by chunk, plus the tile entities in every loaded chunk. Only the top chunks are kept, so the cost stays low even on large servers.
• Redstone: LagTrace counts redstone power changes and piston moves per chunk over a rolling 10–20 second window. This catches clocks, observer chains, piston and flying machines, and dust-heavy contraptions. Block-update spam that changes no redstone power isn't counted. Tracking that would mean listening to an event so frequent that it would cause lag itself.
• Storage: incidents are appended to plugins/LagTrace/incidents.jsonl, one JSON object per line, written in the background. The file is trimmed to max-log-entries at startup (once it's more than twice that size) and every 24 hours. Unreadable lines are skipped with a warning, never a crash.

FAQ

Will it slow my server down? Normally no. Between incidents it only reads one number per second and counts redstone events, which costs about the same as a hashmap update per event. A snapshot usually takes well under 10 ms. If one ever takes longer than max-scan-ms, the cooldown is raised automatically and the console says so.

Why does a snapshot show no hotspots? Chunks only count while they're loaded. With nobody online and no force-loaded chunks, there may be nothing loaded to report.

Does it work without players online? Yes. Lag from force-loaded chunks and farms is recorded even with an empty server.

Can I use it on Folia? Not yet. Folia support is planned for a later version.

License

MIT. See LICENSE.