Prevent Container OOM: Optimize JVM Heap with -XX:MaxRAMPercentage

Background

When a Java‑based service runs with a too‑small JVM heap, it can trigger an Out‑of‑Memory (OOM) event. In container environments the Linux OOM Killer may terminate the process even before the JVM heap reaches its configured limit, causing unexpected restarts.

Limit Heap Size with -XX:MaxRAMPercentage (Recommended)

In containers Java can only see the host resources and not the cgroup limits. Setting -Xmx works but has two main drawbacks:

When the instance size changes, the heap size must be adjusted manually.

Improper values can cause the container to be killed by the OOM Killer before the JVM heap reaches its threshold.

Explanation

When an application runs out of memory, the Linux kernel’s OOM Killer monitors processes that consume excessive memory and forcibly terminates one to free memory, preventing the whole system from crashing.

Recommended JVM Flags

-XX:+UseContainerSupport
-XX:InitialRAMPercentage=70.0
-XX:MaxRAMPercentage=70.0
-XX:MinRAMPercentage=70.0
-XX:+PrintGCDetails
-XX:+PrintGCDateStamps
-Xloggc:/home/admin/nas/gc-${POD_IP}-$(date '+%s').log
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/home/admin/nas/dump-${POD_IP}-$(date '+%s').hprof

Parameter Details

-XX:+UseContainerSupport : Enables the JVM to read cgroup limits (CPU, RAM) from the host. When the container exceeds its memory limit, the JVM throws an OOM exception instead of the container being killed.

-XX:InitialRAMPercentage : Sets the initial percentage of container memory used by the JVM. Recommended to match -XX:MaxRAMPercentage at 70.0%.

-XX:MaxRAMPercentage : Sets the maximum percentage of container memory the JVM may use. Because of system overhead, keep it ≤75.0%; 70.0% is recommended.

-XX:+PrintGCDetails : Enables detailed GC logging.

-XX:+PrintGCDateStamps : Adds timestamps to GC logs (e.g., 2019-12-24T21:53:59.234+0800).

-Xloggc:/home/admin/nas/gc-${POD_IP}-$(date '+%s').log : Specifies the GC log file path; ensure the directory is mounted to a persistent storage.

-XX:+HeapDumpOnOutOfMemoryError : Generates a heap dump automatically when an OOM occurs.

-XX:HeapDumpPath=/home/admin/nas/dump-${POD_IP}-$(date '+%s').hprof : Sets the dump file path; the directory must exist and be mounted to persistent storage.

Common Questions

What does exit code 137 mean for a container?

It indicates the container was killed by the OOM Killer because it exceeded its memory limit. The application’s JVM heap may not have reached its configured maximum, so no dump file is produced. Reduce the JVM heap limit to leave memory for other components.

Why is there no heap dump when OOM occurs?

The Linux OOM Killer may terminate the process before the JVM throws its own OOM, so no dump is generated. Mitigate by reducing the JVM heap size (see recommended flags) or increasing the instance’s memory.

Can heap size be set equal to the instance’s memory?

No. System components consume memory overhead, so the JVM heap must be smaller than the total instance memory to leave room for the OS and other processes.

Why does setting an integer value for -XX:MaxRAMPercentage on JDK 8 cause an error?

It is a known bug in JDK 8 (e.g., version 8u191). Use a decimal value like 70.0 or upgrade to JDK 10 or later.

Solution

Set -XX:MaxRAMPercentage=70.0. If you also use -XX:InitialRAMPercentage or -XX:MinRAMPercentage, do not use integer values.

Upgrade to JDK 10 or newer.

Why does memory usage appear low when the JVM is configured with 6 GB?

The JVM reserves the heap lazily; physical memory is allocated only as the application actually uses it, so usage may start low and increase over time.

Stack Memory Tuning

Garbage Collector Tuning – Throughput‑Oriented

Garbage Collector Tuning – Latency‑Oriented

Auxiliary GC Configurations

Note: The -XX:+UseContainerSupport flag requires JDK 8u191+ or JDK 10+. In JDK 11, use -XX:+PrintGCDetails , -XX:+PrintGCDateStamps , and -Xloggc instead. Ensure the log and dump directories are mounted before the application starts.