Checklags

CheckLags

Find out where your server is lagging and what's causing it!

spark can tell you which plugin or task is eating your tick time. But sometimes that's only half the story. You might know that entities or chunk loading are causing problems, but not where it's happening.

That's what CheckLags is for. It scans loaded chunks, ranks them by estimated lag impact, and gives you an idea of what's causing trouble in each area. This includes mob stacks, item farms, hopper and block-entity clusters, and chunk loading activity.

❓ What is CheckLags?

CheckLags is a server-side tool that helps you find where lag is coming from.

It monitors tick times in the background and starts scanning loaded chunks when TPS drops or unusually slow ticks occur. The results are sorted by heat, making it easier to find areas that might be causing problems.

Here's how it works:

1. CheckLags measures tick duration using Paper's ServerTickEndEvent. If spark is available, it also uses spark's MSPT statistics.
2. When TPS drops or tick spikes occur, CheckLags starts scanning loaded chunks. On Paper and Purpur, scans run asynchronously where possible. On Folia, chunks are scanned through their owning region threads, in 2×2 chunk groups.
3. Each chunk gets a heat score based on its contents and recent activity. Block entities, hostile mobs, dropped items and chunk loading all contribute to the score. Recent lag spikes also influence the result, and an exponential moving average helps smooth out sudden changes.
4. When the server is running normally and nobody is using the plugin, the scanning loop goes idle to keep overhead low.

The scores show relative lag impact, not exact milliseconds per chunk. Minecraft doesn't provide a way to measure tick time for individual chunks. CheckLags is meant to help you find suspicious areas that you can investigate further with spark.

✨ Features

🔥 Find lag hotspots

• /lagcheck top ranks loaded chunks by heat. Click a result to teleport directly to that location.
• /lagcheck watch continuously shows the top 3 hotspots while you try to reproduce the lag.
• Shows possible causes for each hotspot, including mob stacks, item farms, hopper and block-entity clusters, and chunk-loading activity.
• /lagcheck inspect scans a 3×3 chunk area and shows counts for entities, items, block entities and chunk loads, including the most common block-entity types.

🧵 Folia support

• One jar for Paper, Purpur and Folia. The platform is detected automatically.
• Folia scans respect region ownership. Chunks are accessed through their owning region threads.
• /lagcheck region shows the TPS of the Folia region you're currently standing in, alongside global TPS.
• /lagcheck top also displays the TPS of the region containing each listed chunk.

📊 spark integration (optional, recommended)

• When spark is available, CheckLags uses its public statistics API for TPS and MSPT data.
• Uses 5-second TPS and 10-second MSPT windows, which react faster to performance changes than Paper's default 1-minute TPS averages.
• Supports bundled spark on Paper, Purpur and Folia 1.21+, as well as the standalone spark plugin.
• If spark isn't available, CheckLags falls back to Paper's built-in tick statistics.
• /lagcheck stats shows which statistics source is currently being used.

⌨️ Commands

All commands are under /lagcheck. Aliases: /lags and /clag.

Command · Description
/lagcheck top [world] [rows] · Show the chunks with the highest heat scores. Click a row to teleport there.
/lagcheck watch [seconds] · Show the top 3 hotspots repeatedly while testing for lag. Defaults to 120 seconds. Run again to stop.
/lagcheck inspect [world] [cx] [cz] · Scan a 3×3 chunk area and show items, mobs, block entities, chunk loads and the most common block-entity types. Without arguments, scans your current location.
/lagcheck region · Folia only: Show the TPS of your current region compared to global TPS.
/lagcheck stats · Show platform information, spark status, TPS/MSPT data, spike count and chunk-load rate.
/lagcheck reset · Clear the heat map, tick history and chunk-load counters.
/lagcheck reload · Reload config.yml without restarting the server.

Examples:

Permission · Description
checklags.use · Access to all CheckLags commands. Default: OP.

⚙️ Configuration

The configuration file is located here:

plugins/CheckLags/
└── config.yml

Important settings:

spike-threshold-ms: 60 # Tick duration that counts as a spike
tps-alert-threshold: 18.0 # Start scanning when TPS drops below this value
census-interval-ticks: 40 # How often chunks are rescanned while lagging
heat-decay: 0.9 # How quickly old hotspots lose heat

weights: # Adjust these to suit your server
block-entity: 2.0 # Increase for redstone-heavy servers
hostile-mob: 1.0
item: 0.5 # Increase if dropped items are a common problem
chunk-load: 8.0 # Give chunk-loading activity a higher priority

⚠️ Things to keep in mind

• Heat scores are relative. CheckLags helps you find suspicious areas, but it doesn't replace a spark profiler when you need detailed timings.
• Players are excluded from entity counts. Pets and farm animals contribute less to the score than hostile mobs.
• Chunk loads are tracked using a rolling 60-second window per chunk. Areas with frequent chunk loading will receive higher scores.
• Bukkit/Spigot servers are not supported. CheckLags is designed for Paper-based servers.

☕ Feedback and issues

Found a bug or have an idea for a feature? Feel free to DM me on Discord:

Mr_Nova_76