How to Install and Use Spark Profiler on Your Minecraft Server
Install Spark to diagnose lag, monitor TPS, generate flame graphs, and identify the exact plugin or mod causing performance issues on your Minecraft Java server.
Spark is the standard performance profiler for Minecraft servers. It monitors TPS, MSPT, CPU usage, and memory — and most importantly, it generates flame graphs that show exactly which plugin, mod, or game system is eating tick time. If your server has lag, install Spark before changing anything else.
What Spark Tells You
| Metric | What it means |
|---|---|
| TPS (ticks per second) | Should be 20.0. Below 18 = noticeable lag |
| MSPT (ms per tick) | Time per tick. >50 ms = below 20 TPS |
| CPU usage | Per-thread CPU consumption |
| Memory | Heap usage and GC pressure |
| Profiler flame graph | Per-class breakdown of where tick time goes |
Install Spark
Check if Spark is already installed
Paper 1.21+ includes Spark by default. In Console in the XGamingServer Panel, run:
spark tpsIf you get TPS output, you're done. If you see Unknown command, continue.
Download the right Spark build
Go to spark.lucko.me → Downloads and pick the build for your server type:
| Server type | Build |
|---|---|
| Paper / Spigot / Bukkit | spark-X.X.X-bukkit.jar → plugins/ |
| Forge | spark-X.X.X-forge.jar → mods/ |
| NeoForge | spark-X.X.X-neoforge.jar → mods/ |
| Fabric | spark-X.X.X-fabric.jar → mods/ |
| Velocity | spark-X.X.X-velocity.jar → plugins/ |
| BungeeCord | spark-X.X.X-bungeecord.jar → plugins/ |
Upload to your server
Click Files in the panel sidebar. Navigate to plugins/ (or mods/), and upload the Spark JAR.
Restart the server
Restart from Console. Confirm Spark loaded by running /spark tps.
Diagnose Lag with the Profiler
This is the workflow for finding any source of server lag.
Check current TPS
In Console or in-game:
/spark tpsOutput looks like:
TPS from last 5s, 10s, 1m, 5m, 15m: 18.2, 17.8, 19.1, 19.5, 19.8Anything sustained below 18 is a problem.
Start the profiler
/spark profiler startSpark begins recording samples. Let it run for 2–5 minutes during normal gameplay (or while the lag is happening).
Stop the profiler
/spark profiler stopSpark generates a public web URL like https://spark.lucko.me/abc1234. Open it in your browser.
Read the flame graph
The graph shows where tick time is going:
- Wider bars = more time spent in that code
- Top of stack = leaf functions (the actual work)
- Plugin/mod package names (e.g.,
me.someplugin.) reveal the culprit - Look for
MinecraftServer.tickChildrenas the entry — drill down from there
Reading Common Patterns
| What you see in the report | What it means | Fix |
|---|---|---|
EntityType.tick for one mob type | Mob farm with too many of that mob | FarmControl / ClearLagg |
ChunkMap / ChunkHolder | Too many loaded chunks | Lower view-distance |
LevelChunk.tickBlocks | Heavy redstone or block ticks | Switch to Purpur, simplify redstone |
| Specific plugin package wide bars | That plugin is the bottleneck | Update or remove |
GarbageCollector | RAM pressure / GC pauses | Aikar's Flags, right-size RAM |
Pathfinder | Mobs stuck in pathfinding loops | Limit mobs in laggy areas |
BlockPos.getY everywhere | Math overhead from a buggy plugin | Update the plugin |
Memory Diagnostics
If RAM is the problem (frequent OOM, high GC), use:
Check heap usage
/spark healthShows current and max heap, GC stats, and CPU info.
Generate a heap dump
/spark heapdumpCreates a .hprof file you can open in tools like Eclipse MAT or VisualVM to find memory leaks.
Warning: Heap dumps freeze the server briefly and can be hundreds of MB. Run during low-traffic periods.
Command Reference
| Command | Description |
|---|---|
/spark tps | Current TPS over multiple intervals |
/spark health | Server health summary (TPS, MSPT, CPU, RAM, GC) |
/spark profiler start | Start CPU profiling |
/spark profiler stop | Stop and generate report URL |
/spark profiler --interval 4 --thread * | Profile all threads at 4ms intervals |
/spark gc | Garbage collection statistics |
/spark heapdump | Generate .hprof heap dump |
/spark heapsummary | Quick text summary of heap contents |
/spark ping | Show player ping stats |
/spark activity | Recent profiling activity |
Tips for Useful Profiles
- Profile during the actual lag — a profile of a healthy server tells you nothing
- Profile for at least 60 seconds — short profiles miss intermittent issues
- Profile during peak player count — many issues only appear under load
- Don't profile during world generation — chunk gen will dominate the report
- Compare profiles — run one when healthy, one when laggy, and compare
Sharing Spark Reports
Spark reports include a public shareable URL by default. To share with support or our Discord:
/spark profiler stopCopy the URL from chat and paste it. Anyone with the link can view it (no login needed).
Common Mistakes
| Mistake | Fix |
|---|---|
| Stopping the profiler too early | Run for at least 60 seconds, ideally 2–5 minutes |
| Profiling on an empty server | Lag almost always requires player load to reproduce |
| Reading only the top of the flame graph | Drill into tickChildren to find the real cost |
| Reinstalling Spark on every error | The report is the answer — read it carefully |
Ignoring /spark health | It's the fastest way to spot RAM/CPU bottlenecks |
| Asking for help without the link | Always share the Spark URL — text descriptions aren't enough |
Related Guides
How is this guide?
How to Install SkyFactory on Your Minecraft Server
Learn how to set up a SkyFactory modpack server for skyblock gameplay with automation and tech mods.
How to Set Up a Tebex Store for Your Minecraft Server
Create a Tebex webstore to sell ranks, items, and perks on your Minecraft Java server, and link it to your XGamingServer instance with the Tebex plugin.