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.

Permissions

All permissions default to op.

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.

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.