# How to Install and Use Spark Profiler on Your Minecraft Server (/docs/minecraft/setup-spark)



import { Step, Steps } from 'fumadocs-ui/components/steps';

**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 [#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 [#install-spark]

<Steps>
  <Step>
    Check if Spark is already installed [#check-if-spark-is-already-installed]

    Paper 1.21+ includes Spark by default. In **Console** in the [XGamingServer Panel](https://panel.xgamingserver.com), run:

    ```
    spark tps
    ```

    If you get TPS output, you're done. If you see `Unknown command`, continue.
  </Step>

  <Step>
    Download the right Spark build [#download-the-right-spark-build]

    Go to [spark.lucko.me](https://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/` |
  </Step>

  <Step>
    Upload to your server [#upload-to-your-server]

    Click **Files** in the panel sidebar. Navigate to `plugins/` (or `mods/`), and upload the Spark JAR.
  </Step>

  <Step>
    Restart the server [#restart-the-server]

    Restart from **Console**. Confirm Spark loaded by running `/spark tps`.
  </Step>
</Steps>

Diagnose Lag with the Profiler [#diagnose-lag-with-the-profiler]

This is the workflow for finding any source of server lag.

<Steps>
  <Step>
    Check current TPS [#check-current-tps]

    In Console or in-game:

    ```
    /spark tps
    ```

    Output looks like:

    ```
    TPS from last 5s, 10s, 1m, 5m, 15m: 18.2, 17.8, 19.1, 19.5, 19.8
    ```

    Anything sustained below 18 is a problem.
  </Step>

  <Step>
    Start the profiler [#start-the-profiler]

    ```
    /spark profiler start
    ```

    Spark begins recording samples. **Let it run for 2–5 minutes during normal gameplay** (or while the lag is happening).
  </Step>

  <Step>
    Stop the profiler [#stop-the-profiler]

    ```
    /spark profiler stop
    ```

    Spark generates a public web URL like `https://spark.lucko.me/abc1234`. Open it in your browser.
  </Step>

  <Step>
    Read the flame graph [#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.tickChildren`** as the entry — drill down from there
  </Step>
</Steps>

Reading Common Patterns [#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](/docs/minecraft/optimize-server) |
| `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](/docs/minecraft/jvm-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 [#memory-diagnostics]

If RAM is the problem (frequent OOM, high GC), use:

Check heap usage [#check-heap-usage]

```
/spark health
```

Shows current and max heap, GC stats, and CPU info.

Generate a heap dump [#generate-a-heap-dump]

```
/spark heapdump
```

Creates a `.hprof` file you can open in tools like [Eclipse MAT](https://www.eclipse.org/mat/) or [VisualVM](https://visualvm.github.io/) 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-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 [#tips-for-useful-profiles]

1. **Profile during the actual lag** — a profile of a healthy server tells you nothing
2. **Profile for at least 60 seconds** — short profiles miss intermittent issues
3. **Profile during peak player count** — many issues only appear under load
4. **Don't profile during world generation** — chunk gen will dominate the report
5. **Compare profiles** — run one when healthy, one when laggy, and compare

Sharing Spark Reports [#sharing-spark-reports]

Spark reports include a **public shareable URL** by default. To share with support or our [Discord](https://discord.xgamingserver.com/):

```
/spark profiler stop
```

Copy the URL from chat and paste it. Anyone with the link can view it (no login needed).

Common Mistakes [#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 [#related-guides]

* [Optimize Server](/docs/minecraft/optimize-server)
* [Types of Server Lag](/docs/minecraft/types-of-server-lag)
* [Server Tick Loop](/docs/minecraft/fix-server-tick-loop)
* [How Much RAM](/docs/minecraft/how-much-ram)
* [JVM Flags](/docs/minecraft/jvm-flags)
* [Pre-Generate Chunks](/docs/minecraft/pregenerate-chunks)