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.

"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
| Area | Holds | Controlled by |
|---|---|---|
| Heap | Objects and arrays | -Xms, -Xmx, -XX:MaxRAMPercentage |
| Thread stacks | Frames of each platform thread | -Xss, number of threads |
| Metaspace | Class metadata | -XX:MaxMetaspaceSize |
| Code cache | JIT-compiled machine code | -XX:ReservedCodeCacheSize |
| Direct buffers | ByteBuffer.allocateDirect, NIO, Netty | -XX:MaxDirectMemorySize |
| GC structures | Remembered sets, card tables, mark bitmaps | Collector and heap size |
| JVM internals | Symbol tables, compiler arenas, JNI | Mostly 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:
java -XX:NativeMemoryTracking=summary -jar app.jar
jcmd <pid> VM.native_memory summaryThe 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:
- Run with a representative load and NMT on.
- Note heap use after full GC, Metaspace, threads, code cache and direct memory.
- Add headroom of 10 to 20 percent.
- Set the container limit from that total and
MaxRAMPercentageso 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:
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:
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=summaryHere 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:
| Category | Committed |
|---|---|
| Java heap | 1,180 MB |
| Class (Metaspace) | 150 MB |
| Thread (180 threads) | 95 MB |
| Code | 48 MB |
| GC | 60 MB |
| Internal and Symbol | 40 MB |
| Direct buffers | 70 MB |
| Total | 1,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:
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.currentVmRSS 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.


