Using Sampler

Sampler (CF download) is a mod aimed at investigating performance related issues. This page describes how to use it systematically to resolve typical problems.

Identifying the problem

The first step is the rough categorization in client side, server side and low memory issues.

Low memory

The Java virtual machine (JVM) manages memory for the application (=Minecraft) through a garbage collector (GC). As the application requests memory for its operation/data, the JVM will provide some from a pool, the heap. Returning memory back to the heap is done by the GC. The GC detects which data (objects) is no longer in use (reachable) and recycles the space occupied by it for reuse.

Garbage collection is usually a quick and reliable cycle, problems arise if the memory demand exceeds the heap size. The most common fault is configuring insufficient heap space (the -Xmx=<size> JVM parameter), sometimes also memory leaks by faulty mod code, a poor choice of JVM parameters or starting the MC server without nogui.

Typical presentation:

• Unusually long startup time up to freezing completely
• Freezes at runtime, especially client side frame drops right before/when the heap use in F3 drops
• CPU load on all cores during freezes
• Heap usage in F3 or /sampler memory (server) or /csampler memory (client) always close to the upper limit
• High GC counts or time ratios in /sampler memory (server) or /csampler memory (client) - last two rows, both should be well under 30000 "ppm of uptime" several minutes after startup
• Crashes with OutOfMemoryError (GC Overhead exceeded etc.)

Note that freezes and memory demand surges may also have other causes, the symptoms are not 100% reliable indicators.

Client side

Client side issues are problems on the client thread, i.e. the rendering part of game, not the somewhat hidden server thread in single player.

Typical presentation:

• Low frame rate (FPS)
• Frame drops - the game doesn't react smoothly to mouse movement
• Sometimes even freezes, often correlating with lots of chunk updates
• Unsteady frame time debug graph (added by Sampler to F3)
• CPU load on no more than two cores

Freezes overlap symptomatically with low memory issues.

Server side

Anything happening on the dedicated server or the server thread in single player.

Typical presentation:

• Blocks don't break instantly or reappear
• Jittering skybox movement (stars/sun don't move smoothly or jump back in time)
• GUIs (chests etc.) don't open instantly
• "Can't keep up" warnings in the server console/log
• Low average tick rate or tick time spikes (lag spike) as observable through /sampler tps (avg = average, should be ~50 ms, max = maximum within the last ~2 minutes, should be below 500 ms)
• Low or unsteady tick rate observable in F3 (with Sampler installed on both client and server)

Note that Sampler always reports high average and maximum tick times in the first ~2 minutes after startup - the first few ticks are always very slow and bias the statistics. The tick time will routinely go below 50 ms (tick rate over 20) after a lag spike to bring the average rate back in line with the target. The tick rate/time reported by Forge, Minecraft's server GUI or other mods is not reliable!

Network latency (ping) fluctuations, packet loss or generally high network latency causes similar response delays as an overloaded server. Looking at the tick times helps to differentiate between server performance and network problems.