Engine Memory Configuration | Germain Documentation

⚙️ Engine Memory Configuration

Each GermainUX Engine runs in a dedicated Java Virtual Machine. You can adjust its heap allocation from the GermainUX Workspace when the Engine requires more or less memory.

Increase the heap only after confirming that the Engine is memory-constrained and that its host has sufficient available RAM.

📅 When to change Engine memory

Consider increasing the Engine heap when:

Condition
The log contains `OutOfMemoryError`.
The Engine restarts because it exhausts its heap.
Garbage collection causes sustained performance degradation.
Additional monitoring components substantially increase the workload.
GermainUX Support recommends an adjustment.

Do not increase the heap when the host itself is low on memory. In that situation, move components or Engines to another host or add Engine capacity.

🔧 Update the memory setting

In the GermainUX Workspace:

Open Germain > State.
Select the Engines view.
Search for the Engine you want to modify.
Select the Engine.
Locate its JVM options or memory setting.
Update the maximum heap value:
```
-Xmx<size>
```
Save the configuration.
Select Restart this Engine.
Wait for the Engine to return to a running state.

Examples:

-Xmx1024m
-Xmx2g
-Xmx4g

The Engine must restart before the new JVM memory setting takes effect.

📊 Minimum and maximum heap

The two primary memory settings are:

Parameter	Purpose
`-Xms`	Initial JVM heap size
`-Xmx`	Maximum JVM heap size

Example:

-Xms256m
-Xmx1024m

-Xms does not need to equal -Xmx. Increase the initial heap only when the Engine workload and JVM behavior justify it.

Do not configure -Xmx higher than the physical memory available to the Engine after accounting for:

Item
Operating-system memory
Engine Manager memory
Other Engine instances
Native JVM memory
Monitoring tools
Database drivers and native libraries
Other applications running on the host

💡 Default JVM parameters

A standard Engine configuration may include:

-server
-Xms256m
-Xmx1024m
-XX:+CrashOnOutOfMemoryError
-XX:-HeapDumpOnOutOfMemoryError
-XX:-CreateMinidumpOnCrash

Parameter	Purpose
`-server`	Uses the JVM’s server-oriented execution mode
`-Xms256m`	Allocates an initial 256 MB heap
`-Xmx1024m`	Limits the heap to 1 GB
`-XX:+CrashOnOutOfMemoryError`	Terminates the JVM when it cannot continue safely after an out-of-memory condition
`-XX:-HeapDumpOnOutOfMemoryError`	Disables automatic heap-dump generation after an out-of-memory error
`-XX:-CreateMinidumpOnCrash`	Disables JVM minidump creation where the option is supported

The exact defaults may differ by Engine and Java version. Preserve package-supplied options unless you have a documented reason to change them.

✅ Validate the change

After the Engine restarts, confirm that:

Check
The Engine returns to a running state.
Its heartbeat appears in Germain > State.
The process command line contains the new `-Xmx` value.
Monitoring components resume execution.
New telemetry reaches GermainUX.
No invalid JVM-option error appears.
No new memory pressure appears at the host level.

Review the Engine log and effective process command line to verify the applied value.

👀 Monitor the result

After increasing memory, monitor:

Metric
JVM heap utilization
Garbage-collection activity
Host physical-memory usage
Swap or paging activity
Engine CPU utilization
Engine restarts
Component execution time
Local state-store growth

If the Engine remains constrained, determine whether a particular monitoring component is consuming excessive resources.

Possible corrective actions include:

Action
Moving components to another Engine
Moving an Engine to another host
Deploying additional Engine hosts
Reducing unnecessary execution frequency
Correcting a component that retains excessive memory
Increasing host capacity

Troubleshooting

⛔ Engine does not start after the change

Check for:

Problem
Invalid JVM syntax
Unsupported JVM options
A heap value larger than available memory
Duplicate or conflicting `-Xmx` settings
Incorrect units
Java-version compatibility

Restore the previous working value and restart the Engine.

🔁 The new value is not applied

Confirm that:

Check
You modified the correct Engine.
The configuration was saved.
The Engine was restarted.
Another configuration source does not override the setting.
The effective process command line contains only one `-Xmx` value.

🔍 The Engine still reports out-of-memory errors

Verify that:

Check
The new heap value was applied.
The host has enough physical memory.
The workload is appropriate for the Engine.
No component has a memory leak or unusually high demand.
Multiple Engines are not competing for the same host memory.
Native memory—not only Java heap—is not exhausted.

Do not continue increasing the heap indefinitely. Redistribute the workload or investigate the affected component when memory consumption remains abnormal.

Component: Engine

Feature Availability: 2022.1 or later