Diagnosing Low TPS Using a Profiler (Step by Step)

Understanding Minecraft Server Performance

Maintaining a smooth and enjoyable experience on a Minecraft server hinges on its performance, primarily measured by two key metrics: TPS and MSPT. Understanding these concepts is the first step in diagnosing and resolving performance bottlenecks, which often manifest as “lag.”

Key Mechanics of Server Performance

• TPS (Ticks Per Second): Minecraft servers strive to operate at a consistent rate of 20 ticks per second. Each tick represents a fundamental unit of time during which the server processes all game logic. This includes crucial tasks such as mob AI calculations, block updates, player movement, and redstone activations. When a server consistently maintains 20 TPS, players experience seamless gameplay without noticeable delays or stuttering.
• MSPT (Milliseconds Per Tick): This metric quantifies the actual time it takes for the server to complete a single tick. For a server to achieve the target of 20 TPS, each tick must be processed within 50 milliseconds (ms). This is because 1000 milliseconds (1 second) divided by 20 ticks equals 50 milliseconds per tick. If the server’s MSPT regularly surpasses this 50ms threshold, it signifies that the server is struggling to keep up with its workload. Consequently, it will begin to “drop ticks,” leading to a reduction in TPS and, from a player’s perspective, severe lag.

Common Causes of Low TPS

Several factors can contribute to a server’s MSPT exceeding 50ms and thus causing low TPS. Identifying these common culprits is crucial for effective diagnosis:

• Entities: A high concentration of entities is a frequent source of lag. This category includes excessive numbers of mobs (passive and hostile), animals, and dropped items. Complex mob farms, in particular, can generate significant load due to the continuous need for pathfinding AI calculations, collision detection for numerous entities, and constant state updates.
• Chunk Loading/World Generation: The process of generating new terrain in Minecraft is inherently CPU-intensive. When players explore previously unvisited areas, the server must dynamically generate new chunks, which can momentarily spike CPU usage and lead to temporary TPS drops.
• Poorly Optimized Plugins/Mods: While plugins and mods enhance gameplay, poorly coded or inefficient ones can be detrimental to performance. If a plugin or mod executes heavy operations, complex calculations, or extensive data processing on the server’s main thread, it can consume a disproportionate amount of tick time, starving other essential processes.
• Redstone Contraptions: Intricate or poorly designed redstone circuits can generate a massive number of redundant block updates. These unnecessary updates force the server to perform excessive calculations, leading to significant performance overhead.
• Villagers: Villagers, with their complex AI, trading mechanics, and pathfinding routines, can be surprisingly demanding on server resources. A large population of villagers, especially in confined spaces or areas requiring frequent path recalculations, can contribute to lag.
• Command Blocks: Similar to redstone, a high volume of command blocks, especially those running complex commands frequently or targeting large areas, can exert considerable pressure on the server’s CPU, reducing available tick time.

Diagnosing Low TPS with Spark Profiler

To pinpoint the exact cause of low TPS, a profiler is an indispensable tool. The Spark profiler is widely recommended for its ease of use and detailed reports. Here’s a step-by-step guide to using Spark:

Step-by-Step Process (using Spark profiler)

1. Install Spark: Begin by downloading the Spark profiler plugin or mod that is compatible with your specific server software (e.g., Paper, Spigot, Fabric, Forge). Place the downloaded file into your server’s appropriate folder, typically `plugins` for Spigot/Paper or `mods` for Fabric/Forge. It’s worth noting that some optimized server software, such as Paper (from version 1.21 onwards) and Purpur, may include Spark pre-installed, simplifying this step.
2. Check Current TPS: Before starting a detailed profile, get a baseline understanding of your server’s current performance. Use the command /spark tps in the server console or in-game (if you have sufficient permissions). This command provides a quick overview of the current TPS, MSPT, and CPU usage, confirming whether a performance issue is present.
3. Start Profiling: When your server is actively experiencing lag, initiate a profiling session. The command to start a profile is /spark profiler start.
   • For situations where the lag is constant and persistent, a general profile is suitable: /spark profiler --timeout 30. This will record data for 30 seconds.
   • If the lag occurs intermittently or in sudden spikes, a more targeted approach is beneficial: /spark profiler --only-ticks-over 100 --timeout 30. This command instructs Spark to only record data for ticks that take longer than 100 milliseconds to process, effectively capturing only the moments of significant lag within a 30-second window.
4. Allow Profiler to Run: Once initiated, let the profiler collect data for a sufficient duration. While a 30-second timeout is often a good starting point, for a more comprehensive dataset, it’s advisable to let it run for several minutes (e.g., 2-5 minutes), especially while the server is under significant load and actively experiencing the performance issues you aim to diagnose.
5. Stop Profiling: After the desired duration or when the lag event has been captured, conclude the data collection by running the command /spark profiler stop.
6. Access and Analyze Report: Upon stopping the profiler, Spark will generate a unique URL. This URL will be displayed in your server’s chat (for players with permissions) or directly in the server console. Open this link in a web browser to access the detailed performance report. The report is typically presented visually, often as a flame graph or a hierarchical profiler tree, which graphically represents where server time is being spent.
7. Interpret Results: The core of the diagnosis lies in interpreting the Spark report. In the profiler tree or flame graph, focus on entries that show a high percentage of the total tick time. These high-percentage entries directly indicate which tasks, methods, plugins, entities, or world events are consuming the most CPU resources and are therefore the primary contributors to your low TPS. Expand these significant entries to drill down into the specific functions or code paths that are causing the most overhead. For example, if a plugin shows a high percentage, expanding it might reveal a specific method within that plugin that is poorly optimized. Similarly, if entities are a significant factor, you might see specific entity types or AI routines highlighted.

Important Tips for Effective Profiling

• Profile under Load: Always ensure that you run the profiler when your server is actively experiencing lag or when there’s a high number of players online. Profiling an empty or idle server will not yield relevant data regarding the causes of lag during active gameplay, as the problematic processes may not be running or stressed.
• Extended Profiling: To gather a truly comprehensive and representative dataset, allow the profiler to run for several minutes (e.g., 2-5 minutes). Short profiles might miss intermittent spikes or processes that only run occasionally.
• Focus on High Percentages: When analyzing the profiler report, prioritize your investigation into tasks or methods that display the highest percentages of tick time consumption. These are the biggest bottlenecks and addressing them will provide the most significant performance improvements.
• Recreate Lag Scenarios: If your server’s lag is intermittent or occurs only under specific conditions, actively try to trigger those conditions or be present in the areas that cause lag during the profiling period. This ensures that the profiler captures the exact events leading to the performance degradation.
• Consider Server Software: Before even starting to profile, evaluate your server software. Using highly optimized server software like Paper or Purpur, which include numerous performance enhancements and optimizations, can significantly improve your server’s baseline performance and often resolve minor lag issues without extensive profiling.
• Pre-generate Worlds: World generation is a known performance hog. To prevent lag spikes caused by players exploring new territory, consider pre-generating your world using tools such as Chunky during off-peak hours or before your server goes live. This ensures that all necessary chunks are already generated and ready to be loaded quickly.

Common Mistakes to Avoid

While profiling is powerful, certain pitfalls can hinder effective diagnosis:

• Not Using a Profiler: One of the most significant mistakes is attempting to fix lag without first identifying its root cause through profiling. Guesswork or “throwing hardware” (e.g., more RAM, faster CPU) at an undiagnosed problem rarely provides a lasting solution and can be a waste of resources.
• Ignoring MSPT: While TPS is the ultimate indicator of performance, focusing solely on it without considering MSPT provides an incomplete picture. MSPT offers a more granular view of individual tick performance. A server might momentarily show 20 TPS, but if its MSPT is consistently hovering just below 50ms, it indicates that the server is under significant stress and is on the verge of dropping ticks and experiencing lag. High MSPT with seemingly good TPS means the server is struggling to maintain that TPS.
• Profiling an Empty Server: As emphasized earlier, profiling a server that has no players or is not under any load will not provide relevant data. The processes causing lag during active gameplay will likely not be triggered or stressed, leading to a report that doesn’t reflect real-world performance issues.
• Overlooking External Factors: Before diving deep into server-side profiling, it’s crucial to rule out external factors. Personal internet connection issues (such as high ping or packet loss) or problems with your Internet Service Provider (ISP) can often be the real cause of perceived “lag” from a player’s perspective, even if the server itself is running perfectly fine. Always ensure your network connection is stable first.