Identify server performance issues using spark

If you experience lags, make sure to identify the correct kind of lags first. This article explains the different kinds of lags and how you can identify them: Lags

This article helps you to identify server performance issues with your Minecraft: Java Edition server. You have to be able to install the spark mod or plugin on your server. If you currently run a Vanilla server, you should install Paper as your server software, because it allows the installation of plugins and also improves performance: https://exaroton.com/software/papermc/

 

Installation

Spark is available as a mod or plugin and can be installed on most Minecraft: Java Edition servers. You can install it by searching for "spark" in the mod/plugin list or clicking one of the links below:

For most commands in this article, you need permission to use those commands, either by being OP or using a permissions plugin.

 

Minecraft ticks and TPS

If you already know what ticks and TPS, e.g. by reading our Lags article, then you can skip this part.

Minecraft calculates game updates (e.g. plants growing, redstone changes or mob movements) at regular intervals. All of these updates together are called a tick. Minecraft tries to run a new tick every 50 milliseconds, which results in 20 ticks per second. Those Ticks Per Second are often shortened to TPS and are an important metric to measure Minecraft performance. The time a tick takes to calculate is often shortened to MSPT (milliseconds per tick).

If Minecraft can't calculate a tick in 50 milliseconds, then the next tick has to wait for the previous tick to finish. Therefore the game can no longer calculate 20 ticks every second and will slow down which you might notice as lag. When playing online, ticks are entirely calculated on the server, so lower TPS are an indicator of server performance issues.

You can read more about the tick loop in the spark documentation or the Minecraft wiki.

 

View TPS using spark

As explained in our Lags article, you can see the server TPS on exaroton directly, but it's also possible to check the TPS using spark in-game with the command

/spark tps

This shows the average ticks per second (TPS) from different time periods, the tick durations (MSPT) and the CPU usage. The colors also indicate if those values are normal or if there are any performance issues. In general, an average TPS value of 20 is good and your server had no performance issues (in that time period). If you still experience lags with a TPS value of 20, please check out our Lags article.

You can read more about TPS, MSPT, and the spark TPS command in the spark documentation.

 

Creating a spark profile

A spark profile gives you an in-depth view of your server performance and potential bottlenecks. It's captured in-game and displayed on a website with a shareable link. You can start recording a profile with the command

/spark profiler start

The profiler is now running and capturing anything that happens. It is recommended to let the profiler run for several minutes to get a good result. You should also try to recreate any scenario that creates lags for you, e.g. loading a specific area, using a specific item, or running a specific command.

After a few minutes, you can stop the profiler and get a final result using the command

/spark profiler stop

After a few seconds, spark shows you a URL in the chat that you can click on to open your profile.

You can read more about the profiler commands in the spark documentation.

 

Viewing your spark profile

After opening your profile URL, you should see something similar to this:

There is a lot of information in this profile, so let's go through a few important things one by one.

At the top, you see your name and the time that the profile was captured, followed by some buttons to toggle different parts of the viewer.

Below that you can see some general statistics.

You can see the average TPS (ticks per second) for the different time periods as well as the time that it took to calculate one tick in milliseconds (MSPT). After that, you can see the CPU and memory usage of your server.

After that, you can see a graph showing the TPS and MSPT during the entire profiling duration.

Below that graph, you can select different values to show in that graph, e.g. CPU usage. You can only select two different values at the same time, one will have its axis on the left and the other one on the right.

At the bottom of the page, you will find the profiler tree which is initially small and collapsed.

The profiler tree shows different parts of the Minecraft server software and how much time they took to run, by default shown as a percentage.

It is recommended to read the explanation of the profiler tree in the viewer in the spark documentation.

When searching for the cause of performance issues, you are mainly interested in the parts of the software that took the longest time to process. To find those, you start to open the line with the highest percentages layer after layer.

The "Server thread" calculates the server ticks and since it contains every other ticking logic, it will always show 100%. Below that you can see, that java.lang.Thread.run() took 98.03% of the Server thread time to run, so this is what we click on next.

If there is only one element in the next layer, the viewer will automatically open the next one for you. Take a look at the lines on the left to see which elements are on the same layer and check the icons at the beginning of the line to see if an element is open or not.

From this point on, your profiler tree might look entirely different, and you probably have to take a different path to find the cause of your issue. Remember to follow the biggest percentages and try to find something in the lines that you recognize.

In this example, we follow the biggest percentage until we see ...EntityAnimal.aiStep().

 

Entities

A common lag cause in Minecraft is entities. Entity is the general name for all dynamic, moving things in Minecraft, e.g. animals, arrows, boats, or simply any item dropped on the ground. Pretty much everything that isn't a block, is an entity.

You can read more about entities in the Minecraft wiki: https://minecraft.fandom.com/wiki/Entity

As you've seen in the previous example above, entities are also the cause of performance issues in our example profile. You can use the graph in the middle of the page to show you the entity count during your profile, by clicking on "Entities" below the graph.

As you can see, the entity count rises to around 7000 and then falls again and the time it takes to calculate another tick (MSPT) follows the entity count. Together with the result from the profiler tree, we can conclude that too many entities are probably the cause of our performance issue here.

The profile view can also help you find those entities by clicking on the "i" icon in the top bar: 

This opens up more information in the statistics section and also a new section in the middle of the page above the graph with additional information:

Click on the "World" tab to view more information about entities in your world.

Here you can see entity counts per world and the different entities in that world. In this example, you can see that there are over 2,000 cows in the world, most likely the cause of the performance issue. On the right, you can even see in which part of the world those entities are located. You might have to click through the different regions at the top to find them.

In the region overview, you also see a list of chunks ordered by entity count. A chunk is a section of your Minecraft world that's 16x16 blocks in size. So you can convert chunks to coordinates by multiplying them by 16. In this example, to find the 2, 11 chunk, you can teleport to the coordinates 32, 176.

After identifying and finding the problematic entities, you can kill them using the /kill command like this:

/kill @e[type=<entity type>]

In our example, the command to kill all cows would be:

/kill @e[type=minecraft:cow]

You can read more about the /kill command and how to use it in the Minecraft wiki: https://minecraft.fandom.com/wiki/Commands/kill

 

Plugins / Mods

If you use any plugins or mods on your server, then it's possible that one or multiple of them cause performance issues. You can maybe find them by going through the complete profiler tree as described above, but the profile viewer provides an even easier option to see the impact that different plugins or mods have on your server. To open this view, you have to click on the "plugins" or "mods" tab at the top of the page:

Under the graph at the bottom of the page, the profiler tree will be replaced by a plugins/mods view which lists the different plugins/mods and their share in the total calculation time of the server thread.

Plugins or mods with a high percentage are likely to have an impact on the server performance and you can investigate this plugin or mod further or remove it entirely from your server to resolve your performance issues. In our example, you can see that WorldEdit is at almost 30% and is likely the cause for the performance issues during this profile (which was created during a large WorldEdit operation).

 

Additional help and information

If you are unable to identify performance issues with your server, you can contact our support. Make sure to include all relevant information, such as your server software, your server address, your used plugins or mods, and most importantly a link to your spark profile.

 

Spark is a powerful tool that includes way more features and options than we were able to cover in this article. We highly recommend checking out the spark documentation: https://spark.lucko.me/docs/

 

Related articles