> For the complete documentation index, see [llms.txt](https://conboi.gitbook.io/oms-wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://conboi.gitbook.io/oms-wiki/addons/watchdog-essentials/low-memory.md). # Low Memory **Low Memory** is a critical feature provided by the `watchdogessentials` addon.It monitors the server's available memory and takes action when the average available memory over the configured time window falls below a defined threshold. This feature is useful for protecting long-running servers from severe low-memory conditions that may cause performance degradation, instability, or crashes. *** #### Behavior Once enabled, the feature: * Tracks average available server memory over a configurable time window * If the average available memory falls below the configured threshold, performs the configured **critical action**: warning players, requesting a controlled restart, or shutting the server down * Can warn players, request a controlled restart, or shut the server down * Can optionally create a heap dump when a critical memory condition is detected * Attempts to generate a memory report when a low-memory condition is detected, subject to the configured cooldown Memory is checked every 15 seconds and evaluated using the configured averaging window. When `critical_action` is set to `RESTART` or `SHUTDOWN`, the feature requests the stop through OMS instead of stopping the server directly. *** #### Commands Low Memory provides several commands for inspecting the current memory state and generating diagnostic data manually. **Memory Summary** ```bash /oms feature watchdogessentials:low_memory summary ``` Displays the latest memory snapshot, including: * Used memory * Available memory * Currently allocated heap * Maximum JVM heap If no memory snapshots have been collected yet, the command reports that no data is currently available. *** **Memory History** ```bash /oms feature watchdogessentials:low_memory summary over ``` Displays a summary of memory usage over the configured `averaging_window`. You can also specify a custom time window: ```bash /oms feature watchdogessentials:low_memory summary over 1m ``` For example: ```bash /oms feature watchdogessentials:low_memory summary over 5m /oms feature watchdogessentials:low_memory summary over 10m ``` The history summary includes: * Number of collected snapshots * Average used memory * Average available memory * Highest recorded used memory * Lowest recorded available memory *** **Memory Report** ```bash /oms feature watchdogessentials:low_memory report ``` Requests generation of a detailed memory report. Memory reports contain diagnostic information that can be used to inspect the server's memory state and investigate memory-related problems. Generated reports are subject to the configured `memory_report` retention limit and can be found at: ``` oms/watchdogessentials/low-memory/reports ``` *** **Heap Dump** ```bash /oms feature watchdogessentials:low_memory heapdump ``` Requests creation of a JVM heap dump. Heap dumps can be analyzed with external profiling tools to investigate memory leaks and excessive heap usage. Heap dump files can be large and their creation may temporarily affect server performance. Generated heap dumps are subject to the configured `heap_dump` retention limit and can be found at: ``` oms/watchdogessentials/low-memory/heap-dumps ``` *** #### Configuration Config file: ``` world/serverconfig/watchdogessentials-server.toml ``` ```toml [features.low_memory] enabled = true startup_check = true averaging_window = "5m" available_threshold_percent = 10.0 critical_action = "RESTART" create_heap_dump_on_action = false [features.low_memory.cooldowns] warning = "1m" memory_report = "3m" heap_dump = "5m" [features.low_memory.retentions] heap_dump = 3 memory_report = 5 ``` * `enabled` - turns the feature on or off * `startup_check` - checks the JVM maximum heap size at startup and warns if it is below the recommended amount * `averaging_window` - time window used to calculate average available memory * `available_threshold_percent` - percentage of the JVM maximum heap that must remain available; values below this threshold are considered a low-memory condition * `critical_action` - action performed when low memory is detected: `WARNING`, `RESTART`, or `SHUTDOWN` * `create_heap_dump_on_action` - automatically creates a heap dump when a critical memory condition is detected Cooldown settings limit how frequently repeated low-memory actions can produce warnings or diagnostic files. * `warning` - cooldown between low-memory warning messages * `memory_report` - cooldown between automatic memory reports * `heap_dump` - cooldown between automatic heap dumps Retention settings - limit how many generated diagnostic files are kept. When the configured limit is exceeded, older files are removed. * `heap_dump` - maximum number of heap dump files to keep. Default: `3`. Range: `1`–`10`. * `memory_report` - maximum number of memory report files to keep. Default: `5`. Range: `1`–`20`. *** #### Restart Script When `critical_action = "RESTART"`, the feature requests a controlled restart through OMS. OMS performs the shutdown and records that the server should be started again. To complete the restart automatically, run the server using the **OMS restart script** or another compatible restart mechanism. See [**Restart Script Setup**](/oms-wiki/addons/operate-my-server-addon/scheduled-restart/restart-script-setup.md) *** #### Stop Reason This feature introduces two stop reasons: * `watchdogessentials:low_memory_restart` - used when the configured action is `RESTART` * `watchdogessentials:low_memory_shutdown` - used when the configured action is `SHUTDOWN` Both stop reasons include information about the average available memory, averaging window, and configured threshold. {% @github-files/github-code-block url="" %} *** #### Priority This feature is registered with `Priority.CRITICAL`. It monitors memory periodically and has the authority to request a restart or shutdown when a critical low-memory condition is detected. *** #### Source Code This feature is part of the `watchdogessentials` addon. {% embed url="" %}