Elasticsearch Heap Size Setting

The heap size is the amount of memory allocated to the Java Virtual Machine (JVM) that runs Elasticsearch. It's a critical parameter that affects the performance and stability of your Elasticsearch cluster. The heap is used for storing the data structures that Elasticsearch needs to operate, including the inverted index, document store, and various caches. While modern versions of Elasticsearch handle this automatically, understanding heap size configuration is important for optimizing performance and troubleshooting memory-related issues.

Modern Versions (7.x and later)

In modern versions of Elasticsearch (7.x and later), the heap size configuration is optional. Elasticsearch automatically determines the appropriate heap size based on the available system memory. This automatic configuration is generally sufficient for most use cases.

If you need to manually configure the heap size, you can do so by:

Setting the ES_JAVA_OPTS environment variable:

export ES_JAVA_OPTS="-Xms4g -Xmx4g"

Or by adding a file under the jvm.options.d folder (preferred):

-Xms4g
-Xmx4g

Don't verride the default JVM options file (jvm.options) directly, but do it by adding a custom options file,

JVM options files must have the suffix .options and contain a line-delimited list of JVM arguments. JVM processes options files in lexicographic order.

Where you put the JVM options files depends on the type of installation:

tar.gz or .zip: Add custom JVM options files to config/jvm.options.d/.
Debian or RPM: Add custom JVM options files to /etc/elasticsearch/jvm.options.d/.
Docker: Bind mount custom JVM options files into /usr/share/elasticsearch/config/jvm.options.d/.

Legacy Versions (6.x and earlier)

For older versions of Elasticsearch, heap size configuration was more critical. You could set it using:

The ES_HEAP_SIZE environment variable:

export ES_HEAP_SIZE=4g

Or by modifying the jvm.options file:

-Xms4g
-Xmx4g

Best Practices

Set both minimum (-Xms) and maximum (-Xmx) heap size to the same value to prevent heap resizing
Don't set the heap size larger than 50% of available system memory
For production environments, 4GB to 8GB is often a good starting point
Monitor heap usage using Elasticsearch monitoring features or tools like Marvel

Important Notes

Modern versions (7.x+) handle heap size automatically and efficiently
Only modify heap settings if you have specific performance requirements
Always test heap size changes in a non-production environment first
Monitor garbage collection behavior after making changes