Lag diagnostics & auto-tune

Find the chunks and plugins that cause lag, read performance history, get staff lag alerts, and let auto-tune lower the load when the server struggles.

On this page

When players say "the server is lagging", this page helps you answer two questions: where the lag happens and what causes it. Every tool here only measures; nothing changes gameplay except auto-tune and the lag shield, which you have to turn on yourself.

Quick routine when the server lags

  1. Check the current state with nusa status.
  2. Measure the cause with nusa lagchunks start 30.
  3. Read the report: the most expensive chunks and plugins.
  4. Visit the top chunk with /nusa lagchunks tp 1 and look at what is there (farms, hoppers, piled-up mobs).
  5. If lag keeps coming back, look at the pattern with nusa perf and nusa lagspikes.

Finding expensive chunks and plugins (/nusa lagchunks)

nusa lagchunks start 30
nusa lagchunks status
nusa lagchunks report 20
CommandWhat it does
/nusa lagchunks start [seconds]Starts measuring for 5–300 seconds (default 30)
/nusa lagchunks statusShows the progress of the measurement
/nusa lagchunks stopEnds the measurement early
/nusa lagchunks report [rows]Shows the last report again (up to 50 rows)
/nusa lagchunks tp <rank>Teleports you to a chunk from the last report
/nusa lagchunks history [n]Earlier reports, kept across restarts

Each report row shows the world and chunk, its time per tick (ms/tick), its share of the measured time, the dominant category and the most expensive type in that chunk, for example minecraft:hopper.

What is measured: entity ticks, block entity ticks (hoppers, furnaces and similar), scheduled block and fluid ticks, random ticks and natural mob spawning. Chunk loading and networking are not counted per chunk.

The report also has a Plugins section: the time each plugin spends in scheduled tasks and event listeners, with its most expensive task or event.

Performance history (/nusa perf and /nusa lagspikes)

  • /nusa perf shows right now, the last hour and the last day: TPS, average and peak MSPT, peak players, entities, loaded chunks and the number of lag spikes.
  • /nusa lagspikes [page] lists every lag spike, newest first: when, the peak, how long and the cause.
  • /nusa lagspikes info <n> shows one spike in detail, and /nusa lagspikes tp <n> takes you to its most expensive chunk.

History is stored in nusa-perf/history.json (the last 24 hours and the last 100 spikes), so it survives restarts.

Lag alerts for staff

Staff with the nusaspigot.alerts permission (OP by default) get chat messages:

  1. When lag starts: average ms per tick, TPS and whether the cause is being measured.
  2. When the measurement finishes: the main cause and its share, the most expensive chunk and plugin, with Teleport, Full report and Details buttons.
  3. When the server recovers: how long the lag lasted and its peak.

Type /nusa alerts off to mute alerts for yourself until the next restart, and /nusa alerts on to turn them back on.

Auto-tune: lowering the load automatically

Auto-tune is off by default because players can notice it. When it is on, it lowers the server load a little at a time while the server struggles, then gives it back once the server recovers.

It takes steps in this order, starting with what players notice least:

  1. Reduce the entity activation range (distant mobs are ticked less often).
  2. Reduce the simulation distance.
  3. Reduce the view distance.

Auto-tune never goes below the minimums you set, and never edits server.properties or spigot.yml. When the level returns to 0 (and at shutdown), every world gets its own values back.

nusa autotune
nusa autotune on
nusa autotune off
  • nusa autotune shows the current level, thresholds, minimums, the last change, and each world's current and original values.
  • nusa autotune on starts auto-tune without changing the config file (until the next restart).
  • nusa autotune off restores every world and stops auto-tune until the next restart.

Default thresholds: one step down after 10 seconds in a row at 45 ms or more, one step back after 60 seconds in a row at 35 ms or less.

Next steps

Nusa product documentation · NusaSpigotPaper fork · Java 21 / 25

Loading the index…