How to Tune OpenSearch Heap Size to Stop Wazuh High Memory Crashes

If you’re running Wazuh in a production environment and notice persistent memory problems, one of the most common root causes is an incorrectly configured OpenSearch heap size.

Since Wazuh relies on OpenSearch for storing, indexing, searching, and analyzing security events, memory allocation directly impacts overall platform stability and performance.

When the Java Virtual Machine (JVM) heap allocated to OpenSearch is too small, the indexer can struggle to process incoming events efficiently.

When the heap is too large, the operating system loses valuable memory needed for filesystem caching, which can also reduce performance.

Either scenario can lead to excessive memory consumption, degraded search performance, and even service outages.

What the “Wazuh Manager High Memory Usage OpenSearch Heap Size” Issue Looks Like

Many administrators initially assume that the Wazuh manager itself is consuming excessive memory.

In reality, the OpenSearch indexer component is often responsible for the majority of RAM utilization within a Wazuh deployment.

The issue commonly appears after:

• Rapid log growth
• Increased agent counts
• Large retention periods
• Misconfigured JVM settings
• Hardware upgrades without corresponding OpenSearch tuning
• Cluster expansions

Common Symptoms

Administrators experiencing heap-related issues often report:

• OpenSearch consuming excessive RAM
• Wazuh Dashboard becoming slow or unavailable
• Frequent Java OutOfMemoryError events
• OpenSearch node crashes and automatic restarts
• Increased indexing latency
• Delayed alert visibility in the dashboard
• Slow search queries and visualizations
• Elevated CPU usage caused by excessive garbage collection

In severe cases, OpenSearch can become completely unresponsive, causing downstream failures throughout the Wazuh platform.

For broader resource troubleshooting, see our guide on Why Is Wazuh Using High CPU? Troubleshooting Guide.

Why Heap Tuning Is One of the Most Important OpenSearch Performance Optimizations

According to the OpenSearch project, JVM heap allocation is one of the most critical configuration parameters affecting cluster stability and performance.

OpenSearch recommends allocating approximately 50% of available system memory to the JVM heap while leaving sufficient RAM available for the operating system page cache and filesystem cache.

The OpenSearch documentation also notes that improperly sized heaps can cause excessive garbage collection activity, memory pressure, search slowdowns, and cluster instability.

OpenSearch Memory Management Best Practices: https://opensearch.org/docs/latest/install-and-configure/configuring-opensearch/heap/

Additionally, JVM performance experts have long emphasized that larger heaps do not automatically improve performance.

Renowned Java performance engineer Richard Startin has demonstrated that oversized heaps frequently increase garbage collection pause times and can reduce overall application responsiveness.

What You Will Learn in This Guide

In this tutorial, you’ll learn:

• How OpenSearch uses memory within a Wazuh deployment
• How JVM heap allocation works
• Why incorrect heap sizing causes performance problems
• How to identify heap-related memory issues
• How to monitor OpenSearch heap utilization
• How to calculate the proper heap size for your environment
• How to safely adjust OpenSearch heap settings
• How to validate that your changes improved performance
• Best practices for long-term memory management

By the end of this guide, you’ll be able to properly tune OpenSearch heap settings and significantly reduce memory-related crashes, slowdowns, and instability within your Wazuh environment.

For a complete guide, see The Ultimate Wazuh Troubleshooting Guide: Fix Common Issues.

Understanding OpenSearch Memory Usage in Wazuh

Before changing heap settings, it’s important to understand how OpenSearch uses memory and why JVM allocation plays such a significant role in Wazuh performance.

How Wazuh Uses OpenSearch

OpenSearch serves as the primary storage and search engine for Wazuh. Almost every security event processed by the platform eventually passes through the indexer.

Security Event Storage

Wazuh agents generate security events that are forwarded to the manager and ultimately indexed within OpenSearch. Every alert, log entry, vulnerability result, and detection rule match consumes storage and memory resources.

Index Management

OpenSearch continuously creates, updates, merges, and deletes index segments. These operations require memory for metadata management and internal caching.

Search and Analytics

Whenever analysts perform searches or investigate incidents, OpenSearch allocates memory to execute queries and return results.

Dashboard Queries

The Wazuh Dashboard depends heavily on OpenSearch. Every visualization, report, and dashboard widget generates search requests that consume JVM heap resources.

If your dashboard is already experiencing performance issues, you may also find these guides useful:

• Wazuh Dashboard Not Loading? Complete Troubleshooting Guide
• How to Fix “Wazuh Dashboard Server Is Not Ready Yet” (Step-by-Step)

Alert Correlation

Many security detections require correlation across multiple events.

OpenSearch performs aggregations and filtering operations that can become memory intensive as data volume grows.

What Is the JVM Heap?

OpenSearch runs on Java and uses the Java Virtual Machine (JVM) to manage memory.

Definition of Java Heap Memory

The JVM heap is a dedicated region of memory where Java objects are allocated during runtime.

OpenSearch stores many critical data structures within the heap, including:

• Query caches
• Field data
• Cluster metadata
• Search contexts
• Aggregation structures
• Index management objects

Difference Between Heap Memory and System Memory

A common misconception is that heap memory equals total RAM usage.

In reality:

OpenSearch uses all of these memory areas, not just the JVM heap.

Why OpenSearch Relies Heavily on Heap Allocation

Unlike many traditional applications, OpenSearch maintains large in-memory data structures to support:

• Real-time indexing
• Fast search operations
• Aggregations
• Cluster coordination
• Metadata management

Because of this design, heap allocation directly affects cluster responsiveness and stability.

Why Incorrect Heap Size Causes Problems

Improper heap sizing can negatively impact both performance and reliability.

Heap Too Small

When the heap is undersized, OpenSearch constantly struggles to free memory and allocate new objects.

This typically results in:

Frequent Garbage Collection

The JVM spends excessive time reclaiming memory instead of processing requests.

Slow Indexing Performance

Incoming Wazuh events take longer to process and store.

Search Latency Spikes

Queries become slower as memory pressure increases.

OutOfMemoryError Exceptions

The JVM may eventually fail to allocate required objects.

Common log message:

java.lang.OutOfMemoryError: Java heap space

Node Instability

Persistent memory exhaustion can cause node crashes, restarts, or cluster instability.

Heap Too Large

While increasing heap size may seem like an easy fix, allocating too much memory can create different problems.

Long Garbage Collection Pauses

Larger heaps often require longer garbage collection cycles.

According to Oracle JVM tuning guidance, large heaps can increase pause durations because more memory must be scanned and reclaimed during collection cycles.

Oracle JVM Garbage Collection Tuning Guide: https://docs.oracle.com/en/java/

Reduced Filesystem Cache

OpenSearch heavily relies on operating system caching for fast access to index data.

Allocating excessive memory to the JVM leaves less RAM available for filesystem cache.

Increased Memory Pressure

Large heaps can increase overall memory consumption and place additional stress on the operating system.

Lower Overall Performance

Many administrators discover that increasing heap beyond recommended limits actually reduces search throughput and cluster responsiveness.

For this reason, OpenSearch generally recommends keeping heap allocation below approximately 32 GB to preserve compressed object pointers and maximize efficiency.

Symptoms of Heap-Related Memory Problems

Identifying heap-related issues early can prevent major outages and improve cluster stability.

High Memory Usage on the OpenSearch Node

One of the first warning signs is consistently high memory consumption on the OpenSearch server.

On Linux systems, use:

top

or

htop

You can also view memory allocation using:

free -h

Pay particular attention to:

• Available memory
• Cached memory
• Swap utilization
• Java process memory consumption

High RAM usage combined with increasing swap activity is often a strong indicator of heap misconfiguration.

Check OpenSearch Heap Consumption

OpenSearch exposes detailed JVM statistics through its REST API.

Run:

curl -k -u admin:admin https://localhost:9200/_nodes/stats/jvm?pretty

This command returns heap utilization metrics for every node in the cluster.

Key Metrics to Review

Focus on the following values:

heap_used_in_bytes

Current heap consumption.

heap_max_in_bytes

Maximum configured heap size.

heap_used_percent

Percentage of heap currently in use.

A sustained value above 75–85% often indicates growing memory pressure.

GC Collection Counts

Shows how frequently garbage collection events occur.

Rapidly increasing counts may indicate an undersized heap.

GC Collection Time

Measures the amount of time spent performing garbage collection.

Excessive GC time can significantly impact indexing and query performance.

Review OpenSearch Logs

Log files frequently provide the earliest evidence of heap-related problems.

Typical locations include:

/var/log/opensearch/opensearch.log

or

/usr/share/wazuh-indexer/logs/opensearch.log

Common Indicators

Look for messages such as:

OutOfMemoryError

java.lang.OutOfMemoryError: Java heap space

This indicates the JVM cannot allocate additional memory.

CircuitBreakingException

CircuitBreakingException

OpenSearch uses circuit breakers to prevent memory exhaustion before crashes occur.

GC Overhead Limit Exceeded

GC overhead limit exceeded

This means the JVM is spending too much time performing garbage collection.

Heap Pressure Exceeded

Heap pressure warnings indicate that OpenSearch is approaching dangerous memory utilization levels and may begin throttling operations.

If these warnings appear regularly, heap tuning should be treated as a high-priority task before the node becomes unstable or unavailable.

Determining the Correct Heap Size

Choosing the correct OpenSearch heap size is one of the most important decisions when tuning a Wazuh deployment.

A properly sized heap helps prevent memory crashes, improves indexing performance, reduces garbage collection overhead, and ensures long-term cluster stability.

The 50 Percent Rule

OpenSearch follows a widely accepted JVM sizing guideline:

Allocate approximately 50% of available system RAM to the OpenSearch JVM heap.

This recommendation comes directly from OpenSearch and Elasticsearch performance best practices and has been validated through years of production deployments.

https://opensearch.org/docs/latest/install-and-configure/configuring-opensearch/heap/

For example:

• A server with 16 GB RAM should typically use an 8 GB heap.
• A server with 32 GB RAM should typically use a 16 GB heap.
• A server with 64 GB RAM should use approximately 31 GB heap.

Never Exceed 32 GB Heap

One of the most important JVM tuning recommendations is to avoid allocating more than approximately 32 GB of heap memory.

Java uses a memory optimization known as Compressed Ordinary Object Pointers (Compressed OOPs). Once heap allocation exceeds roughly 32 GB, this optimization is disabled, causing:

• Increased memory consumption
• Larger object references
• Lower cache efficiency
• Reduced JVM performance

This is why most OpenSearch experts recommend keeping heap sizes at or below 31 GB, even on servers with significantly more RAM.

Leave Sufficient Memory for Other Components

Many administrators make the mistake of allocating too much RAM to the JVM.

Remember that OpenSearch also requires memory outside the heap.

You should reserve memory for:

Operating System

Linux requires RAM for kernel operations, networking, file handling, and process management.

Filesystem Cache

OpenSearch relies heavily on filesystem caching to accelerate searches and reduce disk I/O.

According to OpenSearch performance documentation, filesystem cache can have a major impact on query latency and indexing throughput.

Wazuh Services

The following services consume additional memory:

• Wazuh Manager
• Wazuh Dashboard
• Filebeat
• Vulnerability Detection modules
• Active Response modules

If you’re seeing memory pressure across multiple Wazuh components, review Why Is Wazuh Using High CPU? Troubleshooting Guide for broader resource optimization techniques.

OpenSearch Native Memory

OpenSearch uses off-heap memory for:

• Network buffers
• Native libraries
• Internal caches
• Thread stacks

Ignoring native memory requirements can lead to unexpected Out Of Memory conditions even when heap utilization appears healthy.

Heap Size Examples

The following table provides a practical starting point for most Wazuh deployments.

These values should be considered baseline recommendations.

Actual requirements depend on event volume, retention periods, search activity, and cluster architecture.

Special Considerations for Wazuh Deployments

Heap requirements vary significantly depending on deployment size and workload characteristics.

Small Deployments

Less Than 100 Agents

Typical characteristics:

• Small businesses
• Test environments
• Home labs
• Limited daily event volume

Recommended starting heap:

2 GB – 4 GB

Most environments in this category rarely require more than 4 GB unless large log sources are being ingested.

Medium Deployments

100–5,000 Agents

Typical characteristics:

• Moderate event volume
• Multiple Linux and Windows endpoints
• Active vulnerability scanning
• Regular dashboard usage

Recommended starting heap:

4 GB – 16 GB

Monitor heap utilization carefully as agent counts increase.

Large Deployments

More Than 5,000 Agents

Typical characteristics:

• Enterprise-scale monitoring
• Large retention requirements
• Frequent searches and dashboards
• High alert volumes

Recommended starting heap:

16 GB – 31 GB

At this scale, cluster design becomes equally important.

You may also benefit from How to Build a Wazuh Indexer Cluster to distribute indexing workloads across multiple nodes.

High-Volume Logging Environments

Some deployments require larger heaps despite having relatively few agents.

Examples include:

Syslog Ingestion

Centralized firewall and network device logging can generate millions of events per day.

See our How to Configure Wazuh as a Centralized Syslog Server guide.

Cloud Audit Logs

AWS CloudTrail and cloud-native telemetry can rapidly increase indexing workloads.

See How to Monitor AWS CloudTrail Logs Using Wazuh.

Endpoint Telemetry

Enhanced endpoint monitoring often produces substantially larger event volumes than traditional log collection.

Threat Hunting Workloads

Frequent searches, aggregations, dashboards, and historical investigations place additional pressure on JVM memory and query caches.

In these scenarios, heap allocation should be based on observed workload metrics rather than agent count alone.

How to Check Current OpenSearch Heap Settings

Before making changes, you should verify your current JVM heap configuration.

This allows you to compare before-and-after performance and confirm whether your current settings align with recommended values.

Locate JVM Configuration

In Wazuh Indexer installations, heap settings are typically stored in:

/etc/wazuh-indexer/jvm.options

This file controls the JVM startup parameters used by OpenSearch.

Verify Current Heap Allocation

Run the following command:

grep "^-Xms\|^-Xmx" /etc/wazuh-indexer/jvm.options

Example output:

-Xms4g
-Xmx4g

These values indicate that OpenSearch starts with a 4 GB heap and can use a maximum of 4 GB.

Understanding Xms and Xmx

The two most important JVM memory parameters are Xms and Xmx.

Xms

Initial heap size allocated when OpenSearch starts.

Example:

-Xms8g

This instructs the JVM to reserve 8 GB of heap memory immediately during startup.

Xmx

Maximum heap size available to the JVM.

Example:

-Xmx8g

This limits heap growth to 8 GB.

Why They Should Match

OpenSearch and OpenSearch Indexer best practices recommend using identical values for both settings.

Example:

-Xms8g
-Xmx8g

This provides several benefits.

Improved Stability

The JVM avoids dynamic heap expansion during runtime.

Reduced Heap Resizing

Heap resizing operations consume CPU resources and can introduce performance fluctuations.

Better Performance

A fixed heap size typically produces more predictable garbage collection behavior and lower latency.

The OpenSearch project specifically recommends setting Xms and Xmx to the same value whenever possible.

How to Increase OpenSearch Heap Size

Once you’ve determined the appropriate heap allocation, you can safely update the JVM configuration.

Step 1: Edit JVM Configuration

Open the configuration file:

sudo nano /etc/wazuh-indexer/jvm.options

Locate the existing heap settings.

Example before:

-Xms4g
-Xmx4g

Example after increasing to 8 GB:

-Xms8g
-Xmx8g

Always ensure both values remain identical.

Step 2: Save Configuration

Before restarting services:

• Verify there are no syntax errors
• Confirm both values match
• Ensure the heap does not exceed available RAM limits
• Confirm the selected heap follows the 50% rule

A common mistake is allocating more memory than the server can safely support, which may prevent OpenSearch from starting.

Step 3: Restart Wazuh Indexer

Apply the changes by restarting the indexer service:

sudo systemctl restart wazuh-indexer

The restart may take several minutes on large clusters.

Step 4: Verify Service Status

After the restart completes, verify that the service started successfully:

sudo systemctl status wazuh-indexer

Expected output should show:

Active: active (running)

If the service fails to start, immediately review the OpenSearch logs for JVM-related errors before attempting additional configuration changes.

You can also validate cluster health after the restart:

curl -k -u admin:admin https://localhost:9200/_cluster/health?pretty

A healthy response should report a green or yellow cluster status, confirming that the node successfully loaded the new heap configuration.

How to Verify the New Heap Configuration

After increasing or adjusting the OpenSearch heap size, it’s important to confirm that the new settings were successfully applied.

Simply editing the jvm.options file does not guarantee the JVM started with the intended configuration.

Verification helps ensure the node is operating with the expected memory allocation and allows you to identify any remaining memory pressure issues.

Check Node JVM Statistics

One of the most reliable ways to validate heap settings is through the OpenSearch JVM statistics API.

Run:

curl -k -u admin:admin https://localhost:9200/_nodes/stats/jvm?pretty

This endpoint provides detailed information about:

• Heap allocation
• Heap usage
• Garbage collection activity
• JVM uptime
• Memory pools
• JVM performance metrics

The output should reflect the new heap size configured in your jvm.options file.

Check OpenSearch Node Information

You can also retrieve node configuration details directly from OpenSearch.

Run:

curl -k -u admin:admin https://localhost:9200/_nodes?pretty

This command displays:

• Node names
• Node roles
• JVM configuration
• Operating system information
• Process details

Reviewing node information helps confirm that all cluster nodes are using consistent memory settings.

Confirm Heap Values

When reviewing the output, focus on the following fields.

heap_max_in_bytes

This value represents the maximum JVM heap available to OpenSearch.

For example:

"heap_max_in_bytes" : 8589934592

This indicates an 8 GB heap allocation.

Verify that this value matches the size configured in:

/etc/wazuh-indexer/jvm.options

heap_used_percent

This metric shows the percentage of heap currently in use.

Example:

"heap_used_percent" : 54

A moderate utilization percentage immediately after startup typically indicates healthy operation.

Node Stability

After applying heap changes, monitor the node for several hours or days and verify:

• No unexpected restarts
• No OutOfMemoryError events
• Reduced garbage collection activity
• Improved dashboard responsiveness
• Stable indexing performance

If dashboard responsiveness remains poor, review Wazuh Dashboard Not Loading? Complete Troubleshooting Guide for additional troubleshooting steps.

Perform a Post-Change Validation Checklist

After modifying heap settings, verify:

1. OpenSearch service starts successfully
2. Cluster health remains green or yellow
3. Heap allocation matches configuration
4.  Heap utilization remains below warning thresholds
5.  Search performance improves
6.  Indexing latency decreases
7. No new JVM-related errors appear in logs

Successful completion of this checklist usually indicates that the heap adjustment was applied correctly.

Additional Methods to Reduce Memory Usage

While heap tuning is often the biggest improvement, memory issues are frequently caused by workload inefficiencies rather than heap size alone.

Optimizing your OpenSearch configuration can significantly reduce memory consumption and improve overall cluster performance.

Optimize Index Retention Policies

One of the most common causes of excessive memory usage is retaining more data than necessary.

As index counts grow, OpenSearch must maintain additional metadata in memory.

Remove Unnecessary Historical Data

Many organizations keep security data far longer than operational requirements justify.

Evaluate:

• Compliance requirements
• Investigation needs
• Storage costs
• Query frequency

Removing obsolete data reduces both storage consumption and heap pressure.

Implement Lifecycle Policies

Index lifecycle management automates data retention and cleanup.

Benefits include:

• Reduced manual administration
• Predictable storage growth
• Lower memory overhead
• Improved cluster performance

Delete Unused Indices

Old test indices, failed imports, and abandoned data sources often remain in clusters indefinitely.

Review existing indices periodically:

curl -k -u admin:admin https://localhost:9200/_cat/indices?v

Remove indices that are no longer required.

Reduce Shard Count

Oversharding is one of the most common OpenSearch performance problems.

Why Excessive Shards Consume Heap Memory

Every shard requires:

• Metadata
• Search context management
• Segment tracking
• Memory allocation

Thousands of small shards can consume substantial heap even when data volumes are relatively low.

According to OpenSearch performance guidance, reducing unnecessary shard counts often provides greater benefits than increasing heap size.

Check Shard Allocation

Use:

curl -k -u admin:admin https://localhost:9200/_cat/shards?v

Look for:

• Large numbers of small shards
• Unbalanced shard distribution
• Excessive shard counts per node

Tune Index Refresh Intervals

OpenSearch refreshes indices periodically to make newly indexed documents searchable.

The default refresh interval may be unnecessarily aggressive for many Wazuh environments.

Benefits of Lower Refresh Frequency

Increasing the refresh interval can:

• Reduce CPU usage
• Lower memory pressure
• Improve indexing throughput
• Reduce segment creation overhead

This is especially useful for high-ingestion environments.

Example configuration:

{
  "index.refresh_interval": "30s"
}

Increasing the interval from 1 second to 30 seconds can significantly reduce indexing overhead without impacting most security operations.

Disable Unused Features

Many environments enable features that are rarely used.

Consider disabling:

Unnecessary Plugins

Unused plugins consume resources and may introduce additional memory overhead.

Unused Dashboards

Dashboards that are never accessed still contribute to index management and stored objects.

Excessive Monitoring Collectors

Collect only the metrics you actively use for troubleshooting and reporting.

Reducing unnecessary monitoring can lower both indexing volume and memory consumption.

Limit Expensive Queries

Certain query patterns can dramatically increase heap utilization.

Wildcard Searches

Queries such as:

*malware*

often require significant memory and CPU resources.

Large Aggregations

Complex aggregations across large datasets consume substantial heap memory.

Deep Pagination

Requests that retrieve large result sets can increase memory consumption and query latency.

Where possible:

• Use filters instead of broad searches
• Limit result sizes
• Restrict aggregation scope
• Optimize dashboards and saved searches

These improvements often reduce memory usage more effectively than simply allocating additional RAM.

Monitoring Heap Usage Over Time

Heap tuning should not be treated as a one-time task.

Continuous monitoring allows administrators to detect memory pressure before it impacts cluster stability.

Monitor Heap Percentages

The most important JVM metric is overall heap utilization.

Track heap usage regularly and establish alert thresholds.

Recommended Thresholds

Below 70% – Healthy

The node has sufficient available memory and is operating normally.

70–85% – Monitor

Sustained utilization in this range may indicate increasing workload demands.

Review:

• Event volume
• Agent growth
• Search activity
• Retention policies

Above 85% – Warning

Memory pressure is becoming significant.

Administrators should investigate:

• Garbage collection activity
• Shard counts
• Query patterns
• Retention settings

Above 95% – Critical

At this level, the risk of:

• Circuit breaker events
• Query failures
• Garbage collection stalls
• OutOfMemoryError exceptions

increases dramatically.

Immediate remediation is recommended.

Track Garbage Collection Activity

Heap utilization alone does not tell the entire story.

Garbage collection metrics provide additional insight into JVM health.

Important Metrics

GC Frequency

How often garbage collection occurs.

Rapidly increasing GC frequency often indicates heap pressure.

GC Duration

How long garbage collection pauses last.

Long pauses can negatively impact:

• Search responsiveness
• Dashboard performance
• Indexing throughput

Heap Recovery Rate

Measure how effectively memory is reclaimed after garbage collection.

Healthy nodes should show a noticeable reduction in heap utilization after major GC cycles.

If heap usage remains consistently high after collection, additional tuning may be required.

Build OpenSearch Monitoring Dashboards

Long-term visibility is essential for proactive capacity planning.

Creating dashboards allows administrators to identify trends before performance problems occur.

Useful Visualizations

Heap Utilization

Track current and historical heap usage percentages.

JVM Memory Trends

Visualize:

• Heap growth
• Peak usage
• Average utilization
• Memory pressure patterns

Search Latency

Monitor whether increasing heap utilization correlates with slower search response times.

Indexing Throughput

Track event ingestion rates and identify periods of elevated workload.

For organizations with large-scale deployments, combining JVM metrics with Wazuh operational metrics provides the most complete picture of cluster health and performance.

As your deployment grows, regular monitoring can help you proactively scale resources, optimize indexing workloads, and prevent future memory-related outages before they affect security operations.

Common Heap Configuration Mistakes

Many Wazuh administrators attempt to solve memory issues simply by increasing the OpenSearch heap size.

While heap tuning is important, several common configuration mistakes can actually worsen performance and increase the likelihood of future outages.

Understanding these pitfalls can save hours of troubleshooting and help maintain a stable OpenSearch environment.

Allocating More Than 32 GB Heap

One of the most common mistakes is assuming that larger heaps always improve performance.

In reality, OpenSearch generally performs best when heap allocation remains below approximately 32 GB.

JVM Compressed Object Pointer Limitations

The Java Virtual Machine uses a memory optimization called Compressed Ordinary Object Pointers (Compressed OOPs).

When heap size exceeds roughly 32 GB:

• Compressed pointers are disabled
• Object references become larger
• Memory efficiency decreases
• JVM overhead increases

This can significantly increase memory consumption even though more heap has been allocated.

Reduced Performance

Administrators often expect a larger heap to reduce memory pressure.

Instead, oversized heaps can produce:

• Longer garbage collection cycles
• Increased JVM pause times
• Higher latency
• Reduced search responsiveness

This is why OpenSearch best practices typically recommend keeping heap allocations at or below 31 GB.

Giving OpenSearch Nearly All System RAM

Another common mistake is allocating excessive memory to the JVM while leaving little RAM available for the operating system.

Example:

Although OpenSearch may start successfully, this configuration often causes severe performance issues.

Starves Filesystem Cache

OpenSearch relies heavily on filesystem caching for fast access to index data.

When insufficient RAM is available for cache:

• Disk reads increase
• Search performance declines
• Query latency rises
• Indexing slows down

Causes Swapping

Linux may begin moving memory pages to disk when available RAM becomes scarce.

Swapping is extremely detrimental to OpenSearch performance and frequently leads to:

• High response times
• Cluster instability
• Node crashes

The OpenSearch project strongly recommends avoiding swap usage whenever possible.

Setting Xms and Xmx Differently

Some administrators configure:

-Xms4g
-Xmx8g

instead of:

-Xms8g
-Xmx8g

Heap Resizing Overhead

When the JVM dynamically expands heap memory, additional CPU resources are consumed.

This can create unnecessary overhead during peak workloads.

Unpredictable Performance

Dynamic heap growth may introduce:

• Latency spikes
• Temporary slowdowns
• Inconsistent garbage collection behavior

For this reason, OpenSearch recommends using identical values for Xms and Xmx.

Ignoring Garbage Collection Metrics

Many administrators focus exclusively on heap utilization percentages.

However, heap usage alone rarely tells the full story.

Hidden Memory Pressure

A node may appear healthy while:

• Garbage collection frequency increases
• Collection times grow longer
• Memory recovery becomes less effective

These are often early warning signs of future problems.

Future Crashes

Ignoring garbage collection trends frequently results in:

• Circuit breaker exceptions
• Search failures
• OutOfMemoryError events
• Unexpected node restarts

Monitoring GC metrics should be part of every production Wazuh deployment.

Increasing Heap Without Finding the Root Cause

Perhaps the most expensive mistake is increasing heap allocation without understanding why memory usage is high.

Heap growth often masks underlying problems rather than solving them.

Common root causes include:

Excessive Shard Count

Too many shards increase metadata overhead and consume large amounts of heap memory.

Oversized Indices

Very large indices can negatively affect query performance and memory utilization.

Query Inefficiencies

Poorly optimized searches may consume substantial heap resources regardless of heap size.

Memory Leaks

Some plugin issues, software bugs, or misconfigurations can cause memory growth that no amount of heap tuning can permanently solve.

Always investigate the underlying cause before allocating additional memory.

Advanced Troubleshooting for Persistent High Memory Usage

If memory utilization remains high after proper heap tuning, deeper analysis may be necessary.

The following techniques can help identify the underlying source of memory pressure.

Analyze OpenSearch Hot Threads

Hot thread analysis helps identify operations consuming excessive CPU or memory resources.

Run:

curl -k -u admin:admin https://localhost:9200/_nodes/hot_threads

Review the output for:

• Long-running searches
• Intensive aggregations
• Segment merges
• Thread contention
• Plugin-related activity

Repeated appearance of the same operation may indicate a performance bottleneck.

Inspect Cluster Health

Cluster health issues often contribute to elevated memory usage.

Check overall cluster status:

curl -k -u admin:admin https://localhost:9200/_cluster/health?pretty

Review:

• Cluster status
• Number of nodes
• Unassigned shards
• Pending tasks
• Relocation activity

Persistent yellow or red states can increase resource consumption and affect memory stability.

Review Index Statistics

Index growth is one of the most common causes of increasing memory utilization.

View index statistics:

curl -k -u admin:admin https://localhost:9200/_cat/indices?v

Look for:

• Extremely large indices
• Unexpected index growth
• High document counts
• Excessive index fragmentation

Questions to ask:

• Are retention policies working correctly?
• Are old indices being deleted?
• Has log volume increased unexpectedly?

These findings often reveal why heap usage continues to rise over time.

Identify Memory-Hungry Queries

Certain search patterns consume disproportionately large amounts of memory.

Aggregations

Large aggregations across millions of documents can rapidly increase heap consumption.

Examples include:

• Terms aggregations
• Cardinality aggregations
• Date histograms
• Multi-level aggregations

Scripted Searches

Script execution adds CPU and memory overhead.

Review dashboards and saved searches for excessive scripting.

Complex Dashboards

Highly detailed dashboards with numerous visualizations may generate dozens of simultaneous queries.

This is particularly common in large Wazuh deployments where analysts monitor:

• Security alerts
• Vulnerabilities
• Endpoint activity
• Threat hunting results

Investigate Potential Memory Leaks

Occasionally, memory growth is caused by software defects rather than configuration issues.

Plugin Issues

Third-party plugins may introduce memory leaks or inefficient memory management.

Temporarily disabling nonessential plugins can help isolate the problem.

Version-Specific Bugs

Both OpenSearch and Wazuh periodically release fixes for memory-related issues.

Review release notes and known issues when troubleshooting persistent memory growth.

Long-Running JVM Processes

Memory leaks often become more apparent over long uptime periods.

Warning signs include:

• Heap usage continuously increases
• Garbage collection becomes less effective
• Memory never fully recovers after GC cycles
• Restarting temporarily resolves the problem

If these symptoms occur, deeper JVM analysis tools may be required to identify retained objects and memory leak sources.

Best Practices for Stable Wazuh OpenSearch Deployments

Preventing memory-related outages is easier than recovering from them.

The following best practices help maintain stable OpenSearch performance as your Wazuh environment grows.

Size Hardware Based on Agent Count

Hardware planning should account for:

• Agent count
• Event volume
• Retention requirements
• Search activity
• Dashboard usage

A deployment monitoring 100 agents has dramatically different requirements than one monitoring 10,000 agents.

Regular capacity planning helps avoid sudden resource shortages.

Maintain Reasonable Heap Allocation

Follow established OpenSearch guidelines:

• Allocate approximately 50% of RAM to heap
• Keep heap below 32 GB
• Use matching Xms and Xmx values
• Leave adequate memory for filesystem cache

Avoid increasing heap unless monitoring data clearly demonstrates the need.

Keep Wazuh Components Updated

Software updates frequently include:

• JVM improvements
• Performance enhancements
• Memory optimizations
• Bug fixes

Maintain current versions of:

• Wazuh Manager
• Wazuh Dashboard
• Wazuh Indexer
• OpenSearch components

Regular updates can eliminate memory issues caused by known defects.

Implement Index Lifecycle Management

Automated lifecycle policies prevent uncontrolled index growth.

Benefits include:

• Lower storage consumption
• Reduced heap pressure
• Improved search performance
• Simplified retention management

Organizations ingesting large volumes of logs should treat lifecycle management as mandatory rather than optional.

Monitor JVM Metrics Continuously

Do not wait until users report performance problems.

Continuously monitor:

• Heap utilization
• Garbage collection frequency
• Garbage collection duration
• Search latency
• Indexing throughput

Proactive monitoring allows teams to identify trends before they become outages.

Regularly Review Cluster Health

Cluster health checks should be part of routine maintenance.

Review regularly:

curl -k -u admin:admin https://localhost:9200/_cluster/health?pretty

Monitor for:

• Unassigned shards
• Node failures
• Relocation activity
• Increasing shard counts
• Cluster status changes

Consistent cluster health monitoring helps prevent many memory-related incidents.

Test Heap Changes During Maintenance Windows

Even relatively small heap adjustments can affect cluster behavior.

Whenever possible:

• Schedule changes during low-traffic periods
• Test modifications in staging environments first
• Document previous settings
• Create rollback procedures
• Monitor JVM metrics immediately after deployment

Following a structured change process minimizes risk and reduces the likelihood of unexpected outages.

By combining proper heap sizing, continuous monitoring, efficient index management, and proactive troubleshooting, most organizations can eliminate the majority of OpenSearch memory issues that lead to Wazuh instability, dashboard slowdowns, and node crashes.

Frequently Asked Questions (FAQ)

Question: What heap size should I use for Wazuh OpenSearch?

The recommended heap size depends on your available system RAM and workload, but the general rule is to allocate about 50% of total memory to OpenSearch.

Typical starting points:

• 8 GB RAM → 4 GB heap
• 16 GB RAM → 8 GB heap
• 32 GB RAM → 16 GB heap
• 64 GB RAM → ~31 GB heap (maximum practical limit)

Always ensure you leave enough memory for filesystem cache, Wazuh services, and the operating system.

Question: Why is OpenSearch using all available memory?

OpenSearch may appear to consume all system memory because it uses multiple memory layers:

• JVM heap memory (primary allocation)
• Off-heap memory (native buffers)
• Filesystem cache (critical for performance)
• Operating system memory

High usage is often normal, but sustained maxed-out memory usually indicates:

• Oversized shard count
• Inefficient queries
• Insufficient hardware resources
• Misconfigured heap size

Question: Should Xms and Xmx be the same value?

Yes. In production Wazuh OpenSearch deployments, Xms and Xmx should always be identical.

Example:

-Xms8g
-Xmx8g

Benefits include:

• Stable memory allocation
• Reduced JVM resizing overhead
• Predictable garbage collection behavior
• Improved performance consistency

Question: Can increasing heap size fix all Wazuh memory issues?

No. Increasing heap size is only a partial solution.

If the root cause is:

• Oversharding
• Inefficient queries
• Excessive indexing volume
• Retention misconfiguration

then increasing heap will only temporarily delay failures rather than solve them.

Question: What happens if heap usage reaches 100%?

When heap usage approaches or reaches 100%, OpenSearch may:

• Trigger circuit breaker exceptions
• Experience severe garbage collection pressure
• Reject queries or indexing requests
• Crash or restart nodes
• Log OutOfMemoryError events

At this point, cluster instability is highly likely.

Question: Is 32 GB the maximum recommended heap size?

Yes, in most cases.

OpenSearch recommends keeping heap size below ~32 GB to preserve:

• Compressed object pointers (Compressed OOPs)
• Memory efficiency
• Garbage collection performance

Even on large servers, 31 GB is typically the upper limit.

Question: How often should I monitor OpenSearch heap usage?

Heap usage should be monitored continuously in production environments.

Recommended frequency:

• Real-time dashboards (preferred)
• Daily operational review
• Automated alerts at 75%, 85%, and 95% thresholds

Monitoring should always include:

• Heap percentage
• Garbage collection activity
• Search latency trends

Question: Does shard count affect heap consumption?

Yes, significantly.

Each shard consumes memory for:

• Metadata
• Segment tracking
• Search context
• Query execution structures

Excessive shard counts are one of the most common causes of high heap usage in Wazuh deployments.

Reducing unnecessary shards often improves performance more effectively than increasing heap size.

Conclusion

Proper OpenSearch heap configuration is one of the most critical factors influencing the stability and performance of a Wazuh deployment.

Recap of Why Heap Sizing Directly Impacts Wazuh Stability

Wazuh relies heavily on OpenSearch for indexing, searching, and analyzing security data. When heap size is incorrectly configured, it can lead to:

• High memory usage and system instability
• Slow dashboard performance
• Frequent garbage collection pauses
• OutOfMemoryError events
• Node restarts and cluster disruption

Conversely, correctly tuned heap settings ensure consistent indexing performance, faster search queries, and a stable monitoring environment.

Summary of Recommended Heap Allocation Guidelines

To maintain optimal performance:

• Allocate approximately 50% of system RAM to OpenSearch heap
• Keep heap size below 32 GB to preserve JVM efficiency
• Always set Xms = Xmx for stability
• Adjust heap size based on workload, not just hardware capacity
• Monitor heap usage continuously to detect early warning signs

These guidelines provide a balanced foundation for most Wazuh deployments, from small environments to large-scale enterprise clusters.

Importance of Balancing JVM Heap with Operating System Resources

One of the most overlooked aspects of OpenSearch tuning is ensuring the operating system has sufficient memory.

A healthy Wazuh OpenSearch deployment requires balance between:

• JVM heap memory (for query execution and indexing)
• Filesystem cache (for fast disk access)
• OS memory (for system stability and background processes)

Over-allocating heap can starve the system of cache memory, while under-allocating it can lead to frequent garbage collection and instability.

Achieving this balance is key to preventing high memory usage issues and ensuring long-term reliability in Wazuh environments.