LagLens

Find where lag comes from, who built it, and fix it safely.

Paper 26.1+ • Java 25 • CoreProtect optional • No player punishments, ever

▌ What is LagLens?

When MSPT climbs, you usually get a number but not a cause.
LagLens gives you the cause.

It counts lag-causing activity in every chunk: redstone, pistons, hoppers, mob spawns, item piles, fluids and TNT. It estimates how much of each server tick that activity costs, asks
CoreProtect who placed the blocks doing the work, and offers
14 one-click remedies. Remedies limit the
contraption, never the player. They're reversible where possible, time-limited and logged.

Code (Text):

▸ H-3fa2 · Redstone clock · world 1204, 64, -338 · ≈2.06 ms/tick (4%) ▲ rising · about 18 pulses/s

  · Builder: Steve 82%, unknown 18%  [TP] [Inspect] [⚡ Redstone freeze]

/ll: server health and the top hotspots, with buttons to teleport, inspect or fix

▌ Features

• Hotspot detection. Activity is grouped into hotspots, ranked by estimated ms per tick and labelled with a cause: redstone clock, hopper chain, mob farm, item pile, fluids/physics or explosives.
• Who built it. CoreProtect looks up the hottest blocks and shows each builder's share, with a confidence rating. Without CoreProtect, LagLens still runs and shows "builder unknown".
• 14 remedies, scoped to the hotspot's chunks only. The gentlest option that fits is always offered first.
• A full GUI dashboard with health, hotspots, remedy picker, active remedies, history, trends, ignored areas, help and settings.
• Smart alerts in chat and on Discord when the server starts lagging, or when a hotspot gets expensive before lag even starts.
• Repeat offenders. LagLens remembers every hotspot, marks places that keep coming back, and shows whose builds keep showing up.
• Ignore areas. If staff check a hotspot and decide it's fine, they can ignore it for a length of time they choose.
• Friendly builder notices. The builder is told what was limited and how to fix their build. Notices only go out when the attribution is trustworthy.
• Lightweight. Analysis runs off the main thread, and /ll self shows exactly what LagLens itself costs per tick.
• Fully restylable. Every message is MiniMessage with a 10-colour theme, so you can recolour the whole plugin from a few hex values.
• Tab completion on every argument, with hover tooltips and a detailed, clickable /ll help.

▌ The Dashboard

Everything is one click away from
/ll menu. The menus are symmetrical, colour-coded and update live.

The dashboard: server health at a glance and a door to every screen

One hotspot in full: what's doing the work, the 5 hottest blocks, who built it, and how to fix it

The remedy picker. Remedies that fit this hotspot glow.

▌ Remedies

Every remedy gets an id (
R-1,
R-2…), is written to the audit log and survives restarts. Undo any reversible remedy with
/ll undo R-12.

• Redstone freeze: holds redstone signals in place so clocks stop (undoable)
• Piston freeze: stops pistons from moving (undoable)
• Dispenser freeze: stops dispensers and droppers (undoable)
• Block disable: removes the single hottest block and keeps it, with its contents, for undo (undoable)
• Hopper throttle: caps hopper transfers per chunk per tick (undoable)
• Hopper freeze: stops every hopper in the hotspot (undoable)
• AI freeze: mobs stay but stop pathfinding (undoable)
• Spawn block: stops spawner, natural and breeding spawns (undoable)
• Fluid freeze: stops water and lava from flowing (undoable)
• Explosion block: stops TNT from priming (undoable)
• Release chunks: clears force-loads and plugin chunk tickets (undoable)
• Entity cap: removes the oldest mobs above the cap (one time, asks to confirm)
• Item clear: removes items lying on the ground (one time, asks to confirm)
• Notify builder: changes nothing, just asks the builder politely to fix it

Named, tamed, leashed and ridden mobs are never touched, and neither are villagers by default. You can also mark spawn and event areas as exempt so they're never remedied. Optional
auto-remedies can act on their own once a hotspot has stayed expensive for a sustained period.

▌ Alerts

Staff with
laglens.alerts get a clickable chat alert:

• when MSPT stays above the threshold (alert mode)
• when a new hotspot reaches the top 3
• when any hotspot passes 2.5 ms/tick, even if the server isn't lagging yet
• with a short summary when they join

You can also post alerts to a
Discord webhook. Mentions are disabled in those posts. Try
/ll alerts test to preview one privately.

A lag alert in chat: click any hotspot to act on it

▌ Trends & Repeat Offenders

LagLens remembers every time a place becomes a hotspot. A place that has been a hotspot
3 times in 7 days gets a
⟳ Repeat marker everywhere it appears. The Trends screen and
/ll trends rank:

• Places: how often, for how long, and the worst cost seen
• Builders: whose builds keep showing up, and where. Only confident CoreProtect results count, so this is a reason for a friendly word, not proof.

Trends: places and builders that keep coming back, over 24 h, 7 d or 30 d

▌ Ignore an Area

Teleported over and the farm is fine? Click
Ignore for… and
choose how long: 30 minutes to 7 days, with no default. The area drops out of lists, alerts, auto-remedies and trends until the time runs out. It stays hidden even if the farm grows. Ignores survive restarts and are logged, and
/ll ignored shows whether an ignored area is still busy underneath.

Staff always choose how long

▌ Telling the Builder

When a remedy is applied, the builder gets a friendly message explaining what was limited, where, for how long, and how to fix their build. If they're offline, they get it on their next join. To avoid blaming the wrong person, notices only go to a builder with at least 40% of the activity, from a lookup that isn't low confidence.

What the builder sees

▌ Commands

Root command
/laglens, alias
/ll. Every argument tab-completes, with tooltips.

Spoiler: All commands

• /ll: server health and the top 3 hotspots
• /ll menu [page|hotspot]: the dashboard
• /ll top [world|count] [count]: ranked hotspot list
• /ll inspect [hotspot|here]: full report for one hotspot
• /ll who <hotspot>: ask CoreProtect who built it
• /ll tp <hotspot>: teleport to the hottest block
• /ll fix <hotspot> <remedy> [duration]: apply a remedy
• /ll undo <remedy-id>: undo a remedy
• /ll active: remedies in effect
• /ll ignore <hotspot|here> <duration> [reason]: ignore an area you've checked
• /ll unignore <id>: stop ignoring an area
• /ll ignored: areas being ignored
• /ll trends [locations|builders] [24h|7d|30d]: repeat offenders
• /ll alerts [on|off|test]: your alerts
• /ll investigate [minutes|stop]: force detailed scanning for a while
• /ll self [reset]: what LagLens itself costs
• /ll reload: reload config and messages
• /ll help [command|topic]: detailed, clickable help

Tab completion with tooltips: a hotspot's cause and cost, what each remedy does

▌ Permissions

Spoiler: Permissions

• laglens.staff: view, inspect, who built it, teleport, alerts, trends, ignore
• laglens.fix: every remedy, plus undo
• laglens.fix.<remedy>: one node per remedy, e.g. laglens.fix.redstone-freeze
• laglens.fix.undo: undo remedies
• laglens.admin: everything, including investigate, self-check and reload

Because each remedy has its own node, helpers can freeze redstone while only admins can remove entities.

▌ Requirements & Install

• Paper (or a fork such as Purpur) for Minecraft 26.1+, running Java 25
• Optional: CoreProtect (API v12+) for builder attribution
• Not supported: plain Spigot and Folia. LagLens uses Paper-only APIs.
• Drop LagLens.jar into plugins/ (and CoreProtect, if you want builder names).
• Start the server. On first start, LagLens downloads its SQLite driver once, so the server needs outbound internet access the first time.
• Run /ll menu. That's it, because the defaults are tuned for most servers.

▌ Good to Know

• Costs are estimates built from activity counts, not a profiler. For code-level detail, LagLens links straight to spark.
• The defaults are based on the game's own numbers (the 50 ms tick, hopper speed, the mob cramming limit) and published server guidance. The included CALIBRATION.md explains every value.
• A developer API lets other plugins read hotspots and listen to (or cancel) remedies through Bukkit events.

Disclaimer: You do not have permission to decompile, edit, or distribute this resource. This resource uses bStats to obtain important metrics and is switched ON by default. You may opt out of bStats metrics on your server at any time, but it is greatly appreciated if you could leave them on. Please respect the licenses of CoreProtect, a soft dependency of LagLens.

Found a bug, have an idea, or need support? Use the discussions tab on this resource as I check it regularly. Please include your server version and the output of /ll self.