Sizing a JVM inside a container: heap percentage, non-heap memory and CPU count

Goal

A container memory limit the JVM will not exceed, and a heap large enough that the collector is not running constantly, both derived from evidence rather than copied numbers.

Prerequisites

A JDK with container support (the java reference describes it as Linux-only and enabled by default, switchable with -XX:-UseContainerSupport), access to the container's cgroup memory limit and CPU quota, and a way to run the service under representative load.

Steps

1. Confirm what the JVM sees: start with -Xlog:os+container=info (the reference names trace for maximum detail) and read the reported memory limit and processor count. -XX:ActiveProcessorCount=n overrides the CPU number when quotas mislead; the reference states this flag is honoured even without container support.
2. Choose a heap percentage, not a fixed size: -XX:MaxRAMPercentage (default 25 percent of the memory available to the process) and -XX:InitialRAMPercentage (default 1.5625 percent) scale with the limit, so one image works in a 1 GB and a 4 GB container. A fixed -Xmx silently exceeds a smaller limit.
3. Budget the non-heap memory the percentage must leave free: class metadata (unbounded by default; -XX:MaxMetaspaceSize caps it), one stack per thread (-Xss, 1024 KB default on Linux/x64 per the reference), direct byte buffers (-XX:MaxDirectMemorySize), the JIT code cache, GC data structures and native libraries. The reference's own example sets -XX:MaxRAMPercentage=75; whatever percentage is chosen is a hypothesis to be measured in step 4, not a known-safe value.
4. Measure the whole process: run under load with -XX:NativeMemoryTracking=summary and jcmd <pid> VM.native_memory summary, then compare the committed total with the container limit and with the cgroup's own memory counter.
5. Set the container limit to the measured peak plus headroom, or lower the heap percentage until the peak fits. Never budget for the heap alone.
6. Re-check the collector choice: the ergonomics chapter selects Serial GC below two processors, so a one-CPU container runs a single-threaded collector unless -XX:+UseG1GC is given deliberately.
7. Record limit, percentage, CPU count and measured peak next to the deployment manifest.

Expected result

The process stays under its limit with a stable resident size, GC logs show a heap that grows to its cap without constant full collections, and resizing the container changes the heap proportionally without a new image.

Limits and test basis

Percentages give unexpectedly small heaps in very small containers; the reference documents -XX:MinRAMPercentage (default 50 percent) for heaps of about 125 MB. Off-heap consumers such as network buffers or memory-mapped files fall outside JVM accounting; the cgroup counter is the final authority. Only the procedure is proposed here; no sizes are claimed for any workload.