Direct answer
Start the spark profiler while the lag is happening, then inspect the hottest relevant thread and call stacks. On current Paper you can use /spark profiler start --timeout 600 to capture a ten-minute sample.
Recommended procedure
- Reproduce the problem at the expected player count and workload. On Paper 1.21+ spark is bundled; otherwise use the official spark release for your platform.
- Start profiling with
/spark profiler start --timeout 600; for manual captures use/spark profiler startfollowed by/spark profiler stop. - Open the returned spark viewer link. Identify the server tick thread (or relevant Folia region threads) and expand the large branches where samples accumulate.
- Look for plugin namespace/class names, world/chunk/entity work or disk/GC-related symptoms. A high percentage reflects sampled work in that profile; it is not proof of a bug without context.
- Record the version, player count and conditions. Change one suspected contributor in staging, then collect a second profile under comparable load.
Why this matters
Profiles reveal where CPU time is spent. Low TPS, latency or memory usage by themselves do not identify the root cause. A profiler run while idle cannot explain lag that occurred earlier.
How to verify the result
- Check that a viewer URL was produced and its capture window includes the slow period.
- Compare the same thread/function branches before and after a change, as well as MSPT and player symptoms.
- Share the report privately with a trusted developer when class names or plugin methods are unclear.
Version and compatibility notes
The thread layout is different on Folia and proxies; do not assume there is one universal server tick thread. /spark profiler start --only-ticks-over 50 is available where the current spark release supports the flag, but the simple timed capture is safer as a default.
Official references
Related guides
Help us improve this article
Tell us what is missing, unclear, outdated, or incorrect. You can also suggest something we should add.