How to read a Spark report for Minecraft server lag

A Spark report looks like a wall of numbers the first time you open it. Most of it can be ignored. This guide shows the few parts that matter, what each one is telling you, and what a healthy report looks like so you know when nothing is wrong.

What it looks like in a Spark report

A Spark report is one long page. From top to bottom it has four parts, and they are best read in this order.

1. The headline numbers. TPS and MSPT first, then tiles for CPU, memory, disk, ping and garbage collection (GC). Spark colours the numbers green, amber or red as a rough guide.
2. The details panel. Server software and version, Java version, how long the server has been running, how long the profile ran, and the mods or plugins installed.
3. The timeline graph. TPS, MSPT, CPU, players, entities and chunks over the length of the profile.
4. The profiler tree. It starts at one line, Server thread at 100%, and expands to show where the time went.

Buttons near the top switch the tree between all (the full tree), flat and mods, and there is a search box for finding a name in the profile.

Step 1: take a profile that can show the lag

A profile only helps if it was taken while the server was lagging, and after the server had been running for a while.

1. Make sure Spark is installed. Some server software includes it. If yours does not, install it from spark.lucko.me.
2. Leave the server running for at least half an hour after a restart, ideally with players online.
3. When the lag is happening, run /spark profiler start --timeout 600 from the console, or in game as an operator. The number is in seconds, so that records for ten minutes.
4. When it finishes, Spark prints a link. That link is your report.

You can also run /spark profiler start and then /spark profiler stop yourself. Ten to fifteen minutes is a good length.

Step 2: TPS and MSPT

TPS is ticks per second. A healthy Minecraft server runs at 20. MSPT is how many milliseconds each tick takes. Every tick has a 50 millisecond budget, because 20 ticks fit into one second.

At the top of the page, TPS is shown as three numbers: the last one, five and fifteen minutes. MSPT is shown as four: the fastest tick, the median, the 95th percentile and the slowest. The 95th percentile means 95 ticks in every 100 were quicker than that number.

If the median is well under 50, the server keeps up and TPS stays at 20. If ticks regularly take longer than 50 ms, TPS drops below 20 and players feel lag. Do not stop at the median. A server can have a fine median and a bad 95th percentile, and that shows up for players as stutter.

The five and fifteen minute TPS cover the server's recent running time, not only the profile. After a recent restart they can look odd, so trust the MSPT numbers and the timeline more.

Step 3: CPU, memory and garbage collection

CPU. Minecraft's main loop runs on a single thread. The CPU figure is a share of the whole machine, so one busy core on a many-core server shows as a small percentage. Do not read low CPU as a sign that all is well, and do not read it as a reason to buy more cores.

Memory. The memory tile at the top compares the Java heap in use with the amount Java has reserved so far, which is not the same as the limit you set with -Xmx. For the real limit, look at the memory figures in the details panel and compare the heap used with the maximum. If heap use is well below the maximum, adding more memory will not help.

Garbage collection. Java regularly stops to clear unused memory. The GC tiles show how many times that happened, how long each took and how often. Many young collections are normal. What to look for is the old collection tile: zero is healthy, while frequent or long old collections mean memory is under pressure. The names depend on the collector, and G1 is the usual one.

Ping. This is mostly the players' connections to the server, not how fast the server is ticking. It is not where server lag shows up.

Step 4: check the details panel before you trust the report

Read the lines about the server and the profile. They tell you whether this report can show the lag at all.

• Uptime. If the server had only been up a few minutes, the profile mostly shows start-up work, which is not typical.
• Profile length. A profile of a few minutes can miss the cause.
• Player count. A profile with nobody online usually shows an idle server.
• Mods and plugins. The list shows what is installed. It is useful for spotting performance mods already in place, so you do not install them twice.

Step 5: the timeline graph

The graph shows how the server behaved over the whole profile. Drag across a section with your cursor to look at just that period, for example a stretch where MSPT climbs.

The buttons under the graph switch lines on and off. Putting entities or players next to MSPT shows whether the lag grows when they do. If MSPT climbs as entities climb, entities are worth a look. If the lag comes in short bursts with a flat line between them, you are looking at spikes, and the cause is usually different from steady lag.

Step 6: the server thread tree

The tree is the part that finds the cause. It starts at Server thread, 100%, which is everything the main thread did during the profile. Click a line to expand it, then keep following the biggest branch. Each line shows the share of the thread's time spent in that piece of code and everything beneath it.

Two things make it easier to read:

• The main thread also spends time waiting for the next tick. On a healthy server the branches that do real work can look small, so compare the work branches with each other rather than expecting them to add up to 100%.
• Names come from the game, a mod or a plugin, so read them as clues. The mods view groups the time by mod or plugin, which is the quickest way to see whether one of them stands out.

Some names you may recognise, though the exact spelling can differ between server software and versions:

• executeTagFunctions: datapack functions that run every tick.
• performCommand under a command block: repeating command blocks.
• findNearestMapStructure: a structure search, which freezes the server for a moment. See server freezes on /locate or explorer maps.

If one branch is clearly larger than the rest, that is your first suspect. If the time is spread thinly with no clear leader, take a longer profile during the lag before you conclude anything. If it is still spread out, the server's CPU speed is the likely limit.

Common mistakes

• Profiling right after a restart. The first 20 to 30 minutes are not typical because the server is still loading chunks and warming up.
• Profiling when nothing is wrong. A report taken in a quiet moment tells you little about the lag players complain about.
• Too short a profile. A minute or two can miss the cause entirely.
• Judging by one spike. A single long tick at start-up is normal. Look at the pattern, not one number.
• Reading only the median. The 95th percentile is closer to what players feel.

If your profile is not telling you much

What to leave alone

• Adding more memory because a number looks large. Check the heap used against the maximum first.
• Adding more CPU cores. The main loop runs on one core, so extra cores do not speed it up.
• Worrying about ping. It mostly reflects the players' connections, not the server's tick.
• Paying for a bigger plan before you have a profile that shows the cause.

Common questions