Skip to content
javahacks.dev
JVM & Performance

JVM Memory Areas Heap Stack Metaspace and Native Memory

Map every region of memory a JVM process uses, from the heap and thread stacks to Metaspace and direct buffers, and measure each with Native Memory Tracking.

6 min read
Summarize in AI
Flat illustration of a heap of objects with the unreachable ones being recycled, with the OpenJDK, Grafana and Linux logos.

"The heap is 2 GB, so why does the container use 3 GB?" is one of the most frequent questions about Java in containers. The heap is one region among several. This post lists them, what controls each and how to see them in a running process. The failure when it goes wrong is described in OOMKilled Java containers. The execution model is in how the JVM works.

The map

AreaHoldsControlled by
HeapObjects and arrays-Xms, -Xmx, -XX:MaxRAMPercentage
Thread stacksFrames of each platform thread-Xss, number of threads
MetaspaceClass metadata-XX:MaxMetaspaceSize
Code cacheJIT-compiled machine code-XX:ReservedCodeCacheSize
Direct buffersByteBuffer.allocateDirect, NIO, Netty-XX:MaxDirectMemorySize
GC structuresRemembered sets, card tables, mark bitmapsCollector and heap size
JVM internalsSymbol tables, compiler arenas, JNIMostly not tunable

The heap is usually the largest. On a 4 GB container with a 2.5 GB heap, the remaining 1.5 GB must hold everything else, and that is not an abundance for an application with many threads and libraries.

The heap

Objects live here and the garbage collector manages them. -XX:MaxRAMPercentage=65 sets the maximum as a share of the container's memory, which is usually a better setting than a fixed -Xmx in a container, because it follows the limit. The generations and regions are described in Java garbage collection explained.

Thread stacks

Each platform thread reserves a stack, typically 1 MB (-Xss changes it), and touches pages as it uses them. A server with 500 threads reserves 500 MB of address space. Virtual threads keep their frames on the heap, so many of them do not multiply stack usage. Deep recursion overflows the stack with StackOverflowError long before the heap matters.

Metaspace and the code cache

Metaspace is native memory for class metadata and grows with the number of loaded classes. A large framework application loads many. Metaspace errors occur when a limit is hit. The code cache holds JIT output; when it fills, the JVM stops compiling and performance drops with a warning in the log.

Direct buffers and native allocations

NIO channels, Netty and some JDBC drivers allocate memory outside the heap. It does not appear in -Xmx, and it is freed when the owning Java object is collected, so it can lag. Libraries with native code (compression, TLS, image handling) allocate through malloc and may fragment.

Measure instead of guessing

Enable Native Memory Tracking and ask for a summary:

Shell
java -XX:NativeMemoryTracking=summary -jar app.jar
jcmd <pid> VM.native_memory summary

The output lists committed memory per category (Java Heap, Class, Thread, Code, GC, Internal, Symbol, Native Memory Tracking itself). NMT adds a small overhead, so enable it in a test environment or briefly. Compare the total with the process's resident set size from the operating system (ps -o rss= -p <pid>) and note what NMT does not see: native libraries and memory from JNI code.

Sizing the container

A practical approach:

  1. Run with a representative load and NMT on.
  2. Note heap use after full GC, Metaspace, threads, code cache and direct memory.
  3. Add headroom of 10 to 20 percent.
  4. Set the container limit from that total and MaxRAMPercentage so the heap is the intended share.

Copying -Xmx from another application skips these steps. If the process is killed, the operating system log says so; see Could not reserve enough space for object heap for the opposite failure, a heap request larger than the machine allows.

Ask the JVM from inside the JVM

The management API reports the pools the JVM already tracks, with no agent and no flags. This program prints the heap, the non-heap total and every memory pool with its usage and limit:

java
import java.lang.management.ManagementFactory;
import java.lang.management.MemoryMXBean;
import java.lang.management.MemoryPoolMXBean;
import java.lang.management.MemoryUsage;

public class MemoryAreas {

    public static void main(String[] args) {
        MemoryMXBean memory = ManagementFactory.getMemoryMXBean();
        print("heap", memory.getHeapMemoryUsage());
        print("non-heap", memory.getNonHeapMemoryUsage());

        for (MemoryPoolMXBean pool : ManagementFactory.getMemoryPoolMXBeans()) {
            print(pool.getName() + " (" + pool.getType() + ")", pool.getUsage());
        }
    }

    private static void print(String label, MemoryUsage usage) {
        System.out.printf("%-45s used=%5d MB committed=%5d MB max=%s%n",
            label, usage.getUsed() >> 20, usage.getCommitted() >> 20,
            usage.getMax() < 0 ? "unbounded" : (usage.getMax() >> 20) + " MB");
    }
}

Run it with java MemoryAreas.java and then again with java -Xmx256m -XX:MaxMetaspaceSize=64m MemoryAreas.java. The names of the pools depend on the collector, so expect G1 Eden Space, G1 Survivor Space and G1 Old Gen under G1, plus Metaspace, Compressed Class Space and the CodeHeap segments under non-heap. A pool with a max of unbounded is one that only the machine limits, and Metaspace is the usual example.

What the container sees

The same numbers matter at the container level. A deployment that makes the budget explicit looks like this:

YAML
containers:
  - name: orders
    image: registry.example.com/orders:1.8
    resources:
      requests:
        memory: "2Gi"
      limits:
        memory: "2Gi"
    env:
      - name: JAVA_TOOL_OPTIONS
        value: >-
          -XX:MaxRAMPercentage=60
          -XX:MaxMetaspaceSize=192m
          -XX:MaxDirectMemorySize=128m
          -Xss512k
          -XX:NativeMemoryTracking=summary

Here the limit is 2 GiB, and the heap takes at most about 1.2 GiB. The remaining 800 MB or so is the budget for Metaspace (up to 192 MB), direct buffers (up to 128 MB), thread stacks, the code cache and the JVM's own structures. Setting MaxDirectMemorySize is worth doing because without it the cap defaults to the heap maximum, and a Netty application can then use heap plus the same again in direct buffers. A fixed 60 percent is a starting point to be checked against NMT, not a rule: an application with few threads and little native code can afford 75, and one with a large Metaspace or many connections needs less.

A budget worked through

Say NMT after a load test reports these committed figures for the process above:

CategoryCommitted
Java heap1,180 MB
Class (Metaspace)150 MB
Thread (180 threads)95 MB
Code48 MB
GC60 MB
Internal and Symbol40 MB
Direct buffers70 MB
Total1,643 MB

That total sits inside 2,048 MB with about 400 MB of margin, which is the room for the spikes NMT does not show: page cache charged to the cgroup, a native library's arena growth and a burst of threads. Read the margin as the real answer. If it is under 10 percent, the pod will be killed on a bad day, and the fix is a bigger limit or a smaller heap, not hope.

Reading the resident set from outside

From a shell inside the container, compare what the JVM says with what the kernel counts:

Shell
jcmd 1 VM.native_memory summary | grep -E "Total|Java Heap|Class|Thread|Code|GC"
grep -E "VmRSS|VmHWM" /proc/1/status
cat /sys/fs/cgroup/memory.current

VmRSS is the resident set now and VmHWM is its peak. memory.current is what the cgroup charges, and it includes page cache, so it can exceed the resident set. A gap between NMT's total and VmRSS of a few hundred megabytes usually points at native libraries or the allocator holding freed memory, and setting MALLOC_ARENA_MAX=2 is the usual first experiment for glibc fragmentation.

Where this model stops

Memory-mapped files count towards resident memory without being in any of these areas, and shared libraries are shared across processes. Cloud runtimes may count memory differently. The HotSpot native memory tracking guide and the [java command reference](https://docs.oracle.com/en/java/javase/25/docs/specs/man/java.html) document the flags.

Also inDebugging
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.