Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Monitoring and Tuning

JVM Memory and Garbage Collection Tuning for Tomcat

Set Tomcat's JVM heap, choose a garbage collector, read GC logs and avoid OutOfMemoryError with practical setenv.sh flags and runnable Java examples.

Tomcat runs inside a Java Virtual Machine, so its memory behavior is the JVM's memory behavior. The defaults are fine for a laptop. In production you must choose a heap size, understand what the garbage collector (GC) is doing, and leave room for memory that is not heap. Mistakes here show up as OutOfMemoryError, long pauses where every request stalls, or a container killed by the operating system for using more memory than it was granted.

This lesson covers the memory areas, the flags you will actually set, how to read GC logs, and a few runnable experiments on the JVM's own behavior. The flags go into bin/setenv.sh and are read-only examples here; Java stand-ins demonstrate the ideas.

Where Tomcat's memory goes

  • Heap: all objects: sessions, cached data, request objects, your application's data. Split into a young generation (new, short-lived objects) and an old generation (long-lived ones).
  • Metaspace: class metadata. It grows with the number of loaded classes and each deployed web application (and each reload) adds its own.
  • Thread stacks: each thread has its own stack (about 1 MB by default). 300 threads cost roughly 300 MB outside the heap.
  • Direct and native memory: NIO buffers, TLS, compression, JNI libraries, the JIT's code cache.

A common mistake is setting -Xmx to the full memory of the machine or container. Total process memory is heap plus metaspace plus stacks plus native, so leave at least 25 to 40 percent of the budget for non-heap use.

Basic flags

Put these in bin/setenv.sh so upgrades keep them:

Terminal
CATALINA_OPTS="$CATALINA_OPTS -Xms2g -Xmx2g \
  -XX:MaxMetaspaceSize=512m \
  -XX:+UseG1GC -XX:MaxGCPauseMillis=200 \
  -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/tomcat/ \
  -Xlog:gc*:file=/var/log/tomcat/gc.log:time,uptime:filecount=5,filesize=20m \
  -Djava.security.egd=file:/dev/urandom"
  • -Xms and -Xmx set the initial and maximum heap. Setting them equal avoids resizing pauses and makes memory use predictable.
  • -XX:+UseG1GC is the default collector on modern JDKs: region-based, with a pause target. -XX:+UseZGC (generational in recent JDKs) targets very short pauses for large heaps; ParallelGC favors throughput over pause time.
  • -XX:MaxMetaspaceSize puts a ceiling on class metadata, turning a runaway classloader leak into a clear error instead of consuming the machine.
  • -XX:+HeapDumpOnOutOfMemoryError writes a .hprof file when the heap fills, which is the most valuable single thing for diagnosing a leak afterward.
  • -Xlog:gc* is the unified GC log for Java 9 and later. Always keep it on in production; its overhead is negligible.

In containers, modern JVMs respect cgroup limits. -XX:MaxRAMPercentage=65 sets the heap as a share of container memory instead of a fixed number, which keeps the flag valid when you resize the container.

Reading GC behavior

A healthy web server shows frequent, quick young collections and rare old ones. Warning signs:

  • Full GCs repeatedly freeing little memory: the old generation is full of live objects (a leak or a heap too small).
  • Pause times of seconds: users see freezes and load balancers mark the node down.
  • Heap after GC that creeps upward over hours: a leak (see memory leaks).
  • GC overhead limit exceeded: the JVM spends nearly all its time collecting and recovers almost nothing.

A GC log line looks like [12.345s][info][gc] GC(18) Pause Young (Normal) (G1 Evacuation Pause) 612M->140M(2048M) 8.331ms. Read it as: heap before, after, total, and the pause. Tools such as GCeasy or the open-source GCViewer parse logs and chart them.

Stand-in: what garbage looks like

This stand-in allocates short-lived objects in a loop, then retains objects in a list, and compares heap use before and after asking for a collection. Exact numbers vary by machine, so the program prints only comparisons that are reliably true.

Java Stand-in: garbage versus retained memory

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The collector frees only what nothing references any more. A leak is the opposite situation: objects you no longer need but that something still points to, such as a static map, so they can never be collected.

Stand-in: an OutOfMemoryError you can catch

OutOfMemoryError is an Error, normally fatal, but a stand-in can provoke one safely by trying to allocate an array far larger than any heap, which the JVM refuses immediately.

Java Stand-in: heap limit message

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

In Tomcat the message you will meet most often is java.lang.OutOfMemoryError: Java heap space (heap too small or a leak), then Metaspace (too many classes loaded or leaking classloaders), and unable to create native thread (too many threads or stack space exhausted). Each has a different fix, which is why the message matters.

A tuning routine

  1. Start with a modest fixed heap (-Xms equal to -Xmx) that fits the machine with headroom.
  2. Turn on GC logging and heap-dump-on-OOM from the beginning.
  3. Run a realistic load test and record: heap after full GC, pause times, GC frequency.
  4. If heap after GC is stable and well below the maximum, you are fine, or can even shrink. If it climbs, look for leaks rather than growing the heap.
  5. Only then tune the collector (pause targets, region size). Most Tomcat servers never need more than a sensible heap and G1.

Session storage deserves a note: 20,000 active sessions of 50 KB each is 1 GB of heap. Keeping sessions small is often the cheapest tuning (sessions).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why not set -Xmx to all of the machine's memory?

    Process memory is heap plus non-heap areas. Without headroom the OS can kill the process.
  2. 2. Which flag writes a diagnostic file when the heap is exhausted?

    The heap dump shows what filled the heap and is the main tool for finding leaks.
  3. 3. What does a heap-after-GC value that rises steadily over hours usually mean?

    After a collection only live objects remain, so a growing floor means something keeps references.
  4. 4. What does OutOfMemoryError: Metaspace point to?

    Metaspace holds class metadata; each redeploy loads new classes, and leaked loaders keep the old ones.

Summary

  • Memory has heap, metaspace, thread stacks and native parts; budget for all of them.
  • Set equal -Xms/-Xmx, G1 as the usual collector, a metaspace cap, GC logs and heap dump on OOM.
  • Read heap-after-GC and pause times; a rising floor means a leak, not a need for more heap.
  • Different OutOfMemoryError messages have different fixes.

Next: Access logs and metrics