3.6 Tomcat Memory Tuning

3.6.1 General Recommendations

Retain automatically tunes on installation, depending on available system memory. Further tuning should not be necessary except in extreme conditions.

By default, Retain detects installed system memory and tunes the maximum memory value according to the following levels:

In general, a minimal install will require 4GB for the OS, the tomcat heap XMS setting (default 4GB), 2GB for Retain and any memory the database requires if installed.

Less than 16 GB system memory:

8 GB: Server and Worker

6 GB: Server only

Less than 20 GB system memory:

12 GB: Server and Worker

10 GB: Server only

More than 20 GB system memory:

16 GB: Server and Worker

14 GB: Server only

In all cases, when only the worker is installed the memory is automatically tuned to 3GB.

To manually tune the memory, carefully consider the following information.

3.6.2 Tomcat Configuration Parameters

There are three significant parameters:

  1. Memory allocated upon Tomcat startup

    • Indicates how much memory is immediately allocated and reserved to Tomcat upon startup. This memory will be in use for the entire lifetime of Tomcat and never available to the other server processes.

    • Typically, this is set to 50%-100% of the maximum memory parameter discusses below. It can be lower, but pre-allocating a sizable percentage of memory enhances performance and reduces memory fragmentation.

  2. Maximum Memory available to Tomcat

    • If the memory usage grows beyond the startup allocation, Tomcat will allocate additional blocks of memory in chunks as needed up to this limit. It will never return this memory to the general server memory pool. (Although memory internally will be freed and reused for Tomcat applications).

    • Tomcat guarantees that it will never exceed this memory allocation parameter. If Tomcat runs out of memory, it will try to reclaim unused memory via garbage collection. If this is insufficient, the web application will be denied the memory allocation. Unpredictable (but invariably unpleasant) results will then occur.

    • This is the most critical parameter to tune, and is the value which is automatically tuned by the installer.

  3. Stack Size

    • For each thread (which includes each and every concurrent user request), Tomcat will allocate stack space.

    • This value is typically measured in KB, and defaults to 512KB.

    • It is allocated per concurrent users, and is in fact far too generous a number in general. 1000 users for example would take 500 MB of RAM just for stack space, before the program even allocates memory to run!

    • Generally, we recommend reducing this number to 160k. Increase conservatively, in 64 KB chunks, if you see out-of-stack-space errors in the logs.

The parameters are abbreviated in the Catalina Opts line as follows:

Stack Size="-Xss<value>k"

Memory Heap="-Xms<value>g"

Maximum Memory=" -Xmx<value>g"

On Linux: edit the following configuration file:

Retain 4.0-


Retain 4.2 or higher


Retain-Tomcat is automatically tuned depending on system memory. To tune the system manually, edit the following lines with the appropriate parameters for your system. For example:

CATALINA_OPTS="-Xms4g -Xmx12g -Xss-256k"

JAVA_OPTS="$JAVA_OPTS -XX:MaxmetaspaceSize=1024m"

On Windows: run the utility to configure Tomcat and modify the appropriate settings.

Retain 4.0-

Retain 4.2 or higher

3.6.3 Checking memory:

After logging into Retain Server, click about link in the upper right of the interface. Among other stats, you'll see the tomcat Memory statistics.

Page File

The page file guide is included here as a courtesy. It is your responsibility to find the proper procedures and documentation from your chosen operating system vendor. The entire responsibility for installation, care, and maintenance of the operating system lies with the customer. We do not provide any kind of support for the operating system.

In some environments, tomcat will run out of resources and crash. Increasing the page file may solve this issue. In some cases doubling the page file was sufficient, in other cases increasing it to 64GB was sufficient.