How to run a Spark Profiler diagnosis on your Minecraft server

[BoxToPlay-helper]

How to run a Spark Profiler diagnosis on your Minecraft server

Spark is a powerful profiler that helps you understand what is slowing down your Minecraft server: heavy mods or plugins, slow tasks, long ticks, and more. At BoxToPlay, you can easily install Spark as a mod or plugin directly from the BoxToPlay panel (or manually by uploading the file via FTP) and run all diagnostics from the live console.

Below we explain how to install and use Spark on your server.

1. Prerequisites

Before launching Spark Profiler on your Minecraft server:

• A Minecraft server on BoxToPlay started and online.
• The server must run a version that supports mods or plugins (Forge, NeoForge, Fabric, Spigot, Paper, Purpur, etc.). Spark is also compatible with proxies (BungeeCord, Velocity).
• Access to the BoxToPlay live console for this server with sufficient permissions to run Spark commands.

2. Install Spark on your server

Spark adapts to all server environments. Depending on your setup, you can choose one of the two following methods:

Option A: Automatic installation via the BoxToPlay Panel

This is the fastest and most convenient method:

1. In your server menu on the BoxToPlay panel, click on Installation of Mods or Installation of Plugins (depending on your server type).
2. Type spark in the search field.
3. Select the spark mod or plugin.
4. Choose the version that matches your server/Minecraft version (e.g. Forge, Fabric, Paper/Spigot, etc.).
5. Click Install and confirm.
6. Once the installation is complete, restart the server to load Spark.

Option B: Manual installation (via FTP or File Manager)

If you prefer to upload the file yourself or use a specific build:

1. Download the appropriate Spark .jar file from the official Spark website, Modrinth, or CurseForge. Make sure to download the exact file matching your server platform (Forge, Fabric, Spigot/Paper, BungeeCord, Velocity, etc.) and your Minecraft version.
2. Connect to your server using FTP or open the File Manager in the panel.
3. Upload the .jar file to the correct directory:
   • For plugin-based servers (Spigot, Paper, Purpur…): upload to the plugins/ directory.
   • For modded servers (Forge, NeoForge, Fabric…): upload to the mods/ directory.
4. Restart the server to apply the installation.

3. Confirm that Spark loads in the server logs

1. Go back to the Dashboard for the server and make sure it is Online.
2. Click Server logs from the live console header or open the All logs page.
3. Search the latest startup log for entries mentioning spark (lines indicating that Spark has been initialized as a mod or plugin, version loaded, etc.).

If Spark does not load at startup:

• Double-check that the .jar file is in the correct directory (mods/ or plugins/) and that the server has been restarted.
• For automatic installation via the panel, verify that the mod/plugin is active in the installed mods/plugins management tab.

4. Running Spark Commands (Console or In-game)

You can execute Spark commands in two different ways:

• From the BoxToPlay live console: Go to your server Dashboard in the panel and type the commands in the terminal input field at the bottom without a leading slash (e.g., spark profiler start).
• Directly in-game: If you are logged into your server and have the necessary permissions (OP or specific spark.profiler permission nodes), you can run commands directly in the game chat by adding a slash / (e.g., /spark profiler start).

5. Start a Spark Profiler session

Spark offers several profiling modes depending on your needs.

Note: If you are running Spark on a proxy server, the base command changes depending on the platform: use sparkb on BungeeCord and sparkv on Velocity (e.g., /sparkb profiler start or /sparkv profiler start). Note that installing Spark on a proxy only profiles the proxy itself (network handling, proxy plugins, etc.). To profile your backend game servers (Paper, Fabric, etc.) connected to the proxy, you must install Spark on each game server individually.

For a classic 120-second diagnosis, use:

spark profiler start --timeout 120

Spark will automatically stop the capture at the end of the timeout and generate the report link. If you want to stop the capture manually before that, use:

spark profiler stop

To monitor the capture session without stopping it, you have two useful commands:

• To display the status and technical details of the current recording in the console/chat (duration, number of samples, etc.):

  spark profiler info
  

• To generate a link that allows you to view the live report and watch the data update in real-time in your browser while the capture is still running:

  spark profiler open
  

To investigate isolated lag spikes, start by enabling the tick monitor:

spark tickmonitor --threshold-tick 50

Once you have identified unusually long ticks, start a targeted profile. For example, to collect only ticks above 150 ms:

spark profiler start --only-ticks-over 150 --timeout 120

For more advanced diagnostics, Spark allows you to modify the scope or type of data analyzed:

• Profile all threads (instead of limiting tracking to the main server thread): useful if lag is caused by asynchronous tasks, network connections, or other processes running in the background.

  spark profiler start --thread * --timeout 120
  

• Profile memory allocation (instead of CPU usage): tracks object allocation in memory to find the root cause of RAM leaks or heavy garbage collection (GC) activity.

  spark profiler start --alloc --timeout 120
  

Always adapt the exact syntax to what your Spark version shows in console help (spark or spark help).

Good practices during profiling:

• Choose a representative period: launch the profile during normal or peak play, not right after startup.
• Avoid restarting or stopping the server during the run.
• Try to reproduce any lag you’re investigating while the profiler is running.
• A duration between 60 and 180 seconds is usually enough to get useful data.

6. Wait for the analysis and get the profiling link

1. After you launch the profiling command, Spark will confirm in the console that profiling has started.
2. Let the server run normally until Spark prints a completion message.
3. At the end, Spark generates a URL (profiling report link) and prints it directly in the console.
4. Copy this link from the live console.

This link is the central piece of your analysis: keep it somewhere safe to review or share later.

This header section of the report summarizes the overall health of your server at a glance:

• TPS (Ticks Per Second): The number of game ticks processed per second. The optimal value is 20.00. A sustained drop in TPS translates directly to visible server-side lag for players.
• MSPT (Milliseconds Per Tick): The time (in milliseconds) taken to compute a single tick. To maintain a perfect 20.00 TPS, this value must remain below 50.00 ms. If the average or median MSPT exceeds 50 ms, the server cannot keep up and the TPS will drop.
• CPU: The percentage of CPU power consumed by your server process.
• Memory: The amount of RAM currently used out of the maximum memory allocated to the server.

7. Reading the Spark Profiler report

When you open the Spark profiling link in your browser, you get an interactive report. Key sections to review:

• Tick / TPS timeline
  • Shows average tick time and TPS during recording.
  • Look for spikes above 50 ms per tick (severe lag) or long periods below 20 TPS.

• Top contributors by tick time

  • Lists which mods or plugins, entities, or systems consume the most tick time.
  • Identify:
    • Heavy mods/plugins (e.g. world-generation, complex automation, unoptimized plugins).
    • Problematic dimensions or areas.
    • Expensive tasks triggered on every tick.

• Schedulers / tasks

  • Spark shows scheduled tasks (repeating tasks, timers, async tasks).
  • Watch for tasks running too often (every tick) or taking a long duration.

• Garbage Collector (GC) information

  • Check the time spent in GC pauses and memory usage curve.
  • Frequent or long GC pauses usually mean:
    • Too many allocations from mods or plugins.
    • Insufficient RAM for the workload.

• CPU hot paths (in CPU profiles)

  • Flame graphs highlight which methods consume the most CPU.
  • Focus on the top few stacks; they often point to the exact feature, plugin, or mod causing lag.

Use these insights to decide what to change: reduce view distance, adjust settings, remove or replace a problematic mod/plugin, or re-schedule heavy tasks.

8. Re-profile after changes

Whenever you change configuration or add/remove mods or plugins, it’s a good practice to run a new Spark profile to confirm that performance has actually improved.

• Keep multiple profile links with labels (before/after change).
• Compare tick times, GC behavior, and top contributors.

Conclusion & next steps with BoxToPlay

Spark Profiler is one of the most effective tools to understand what happens inside your Minecraft server hosting environment. Thanks to the simplified installation of mods and plugins and the live console in the BoxToPlay panel, you can install Spark, profile your server and act on the results in just a few minutes.

If you want to test these steps on your own world, you can create a Minecraft server on BoxToPlay and experiment with Spark without commitment. Start your free trial and launch your optimized server today.