The spark profiler: finding what slows your server down

In short: wait for the lag and run /spark profiler start --timeout 600. After 10 minutes spark posts a link to the report. Open the "Server thread" there and follow the largest percentages; the "Sources" view shows a separate tree for every plugin. For rare freezes add --only-ticks-over 100 — only ticks longer than 100 ms make it into the report.

Installation: Paper already has it#

Since 1.21 Paper ships with spark built in, so there's no jar to install — /spark works right away. It's controlled by the spark section in config/paper-global.yml: enabled: true turns the bundled spark on, and enable-immediately: false means it starts after the Done line in the console. To profile server startup itself, set enable-immediately: true.

• You need a newer version than the bundled one. Put the spark jar in plugins/ and add -Dpaper.preferSparkPlugin=true to the start command.
• Other servers. Download the jar from spark's downloads page, put it in the plugins or mods folder and restart.
• Proxies. On Velocity the command is /sparkv, on BungeeCord /sparkb.
• Permissions. The general spark permission or specific ones: spark.profiler, spark.health, spark.tps, spark.gc, spark.heapsummary. Operators have access anyway.

The main commands#

The profiler and its flags#

/spark profiler start --timeout 600
/spark profiler start --only-ticks-over 100 --timeout 600
/spark profiler start --thread * --timeout 600
/spark profiler open

A profile is only useful while the problem is happening — Paper's docs say so too. Take it at peak online or when players complain, not on an empty server. On Linux and macOS (x86_64 and arm64) spark uses the async-profiler engine, which is more accurate than the Java sampler. In containers such as Pterodactyl it may need the libstdc++ package.

Rare freezes: tickmonitor and --only-ticks-over#

A normal profile averages everything: one 300 ms tick drowns among thousands of normal ones. spark's docs suggest a two-step approach.

1. 1

   Catch the freeze

   /spark tickmonitor --threshold-tick 50 reports every tick over 50 ms — the point where the server starts falling behind. Without flags the monitor reports ticks that take twice the average.

2. 2

   Gauge the duration

   See how long the laggy ticks last and line the timing up with what was happening in game.

3. 3

   Profile only the freezes

   /spark profiler start --only-ticks-over 100. The threshold must be below the laggy ticks' duration; spark suggests a value between 50 and 100 ms.

How to read the report#

1. 1

   Pick the thread

   At the top is the list of threads. The key one is "Server thread": it runs the tick. A thread always shows 100%; below it are shares of its time.

2. 2

   Separate sleep from work

   Time spent waiting for the next tick (waitForNextTick, sleep) is good: the server has headroom. Per spark's docs, under 20% sleep means the server is working hard, and under 5% means it's almost certainly lagging.

3. 3

   Follow the percentages

   Expand the nodes with the largest share: world ticking, entities, plugin scheduler tasks. Hover to see the time in milliseconds.

4. 4

   Switch to "Sources"

   The "Sources" view builds a separate tree for every plugin, so you see right away how much of the tick each plugin takes.

Memory and garbage collection#

/spark health show --memory prints JVM memory details to the console, and /spark gc shows the garbage collection history. If memory keeps growing and isn't freed, /spark heapsummary shows which classes fill the heap: the package names usually tell you whose plugin it is. /spark heapdump writes a full .hprof snapshot — it's big, so keep disk space free. How much memory to give the server is in how much RAM a server needs, and which collector flags to use is in JVM flags.

Sharing a report#

You can freely send the report link to a plugin developer or to support: Paper's docs ask you to bring a spark report to the #paper-help channel on their Discord. If you'd rather not upload the profile to spark's site, stop the profiler with --save-to-file. A rundown of the usual causes of lag is in why your server lags and Paper optimization.

Check your anticheat in the profile#

A spark profile is an honest way to check any plugin, the anticheat included: find it in the "Sources" view and look at its share of the "Server thread". DGuard — the best anticheat for a modern Minecraft server — runs its checks on network threads, so its main thread cost is 0.03% of one core. A profile with --thread * shows the work on network threads, and /dguard perf shows the time the checks themselves take. How to compare two anticheats on one server is in anticheat performance.

FAQ#