Class MemoryMonitor

java.lang.Object
org.infinispan.commons.util.MemoryMonitor
public class MemoryMonitor extends Object
Monitors JVM memory usage and garbage collection activity, raising alerts when configurable thresholds are exceeded.

Two types of conditions are tracked:

  • Memory threshold — alerts when old generation heap usage exceeds a configured fraction of the maximum heap. The alert auto-clears after a GC if usage drops back below the threshold. Requires a JVM that exposes an old generation memory pool with usage threshold support. All collectors on JDK 25+ are supported; on older JDKs, ZGC and non-generational Shenandoah may lack this, in which case the monitor is automatically disabled and a warning is logged.
  • GC pressure — alerts when the ratio of time spent in GC over a rolling window exceeds a configured fraction. Auto-clears when pressure drops below the threshold.

Individual GC pauses exceeding the duration threshold are logged as warnings but do not raise a persistent alert.

All thresholds are mutable at runtime. A single instance is registered per cache manager in the GlobalComponentRegistry.

Since:
16.2

  • Constructor Details

    • MemoryMonitor

      public MemoryMonitor(double memoryThresholdPercentage, long gcDurationThresholdMs, double gcPressureThreshold, long gcPressureWindowMs)
      Creates a new monitor with the specified thresholds and immediately registers JMX listeners.
      Parameters:
      memoryThresholdPercentage - fraction (0, 1.0] of old gen usage that triggers a low memory alert
      gcDurationThresholdMs - GC pause duration in ms above which a warning is logged
      gcPressureThreshold - fraction (0, 1.0] of time spent in GC over the pressure window that triggers an alert
      gcPressureWindowMs - rolling window in ms over which GC pressure is computed

    • MemoryMonitor

      public MemoryMonitor()
      Creates a new monitor with default thresholds: 85% memory, 5000ms GC duration, 20% GC pressure over a 60s window.

  • Method Details

    • stop

      public void stop()
      Removes all registered JMX notification listeners. Called during cache manager shutdown.

    • recordGcEvent

      public void recordGcEvent(long timestampMs, long durationMs)

    • addListener

      public void addListener(MemoryMonitor.Listener listener, Executor executor)
      Registers a listener that will be notified of memory state transitions.

      Callbacks are dispatched on the provided executor rather than on the JMX notification thread. This is required because JMX notification delivery is synchronous — blocking in a callback would stall all subsequent notifications for the entire JVM. The executor also decouples the listener's concurrency model from the monitor's internals.

      Parameters:
      listener - the listener to notify
      executor - the executor on which callbacks will be invoked

    • removeListener

      public void removeListener(MemoryMonitor.Listener listener)
      Removes a previously registered listener.

    • simulateMemoryLow

      public void simulateMemoryLow()

    • simulateMemoryRecovered

      public void simulateMemoryRecovered()

    • isMemoryLow

      public boolean isMemoryLow()
      Returns:
      true if old generation heap usage has exceeded the memory threshold

    • isGcPressureExceeded

      public boolean isGcPressureExceeded()
      Returns:
      true if GC time over the pressure window has exceeded the pressure threshold

    • reset

      public void reset()
      Clears all alerts and discards recorded GC events.

    • setMemoryThreshold

      public void setMemoryThreshold(double percentage)
      Sets the old generation heap usage threshold. Clears any active low memory alert and re-applies the threshold to the memory pool.
      Parameters:
      percentage - fraction (0, 1.0]
      Throws:
      CacheConfigurationException - if the value is out of range

    • setGcDurationThreshold

      public void setGcDurationThreshold(long durationMs)
      Sets the GC pause duration threshold for log warnings.
      Parameters:
      durationMs - duration in milliseconds, must be positive
      Throws:
      CacheConfigurationException - if the value is not positive

    • setGcPressureThreshold

      public void setGcPressureThreshold(double percentage)
      Sets the GC pressure threshold. Clears any active GC pressure alert.
      Parameters:
      percentage - fraction (0, 1.0]
      Throws:
      CacheConfigurationException - if the value is out of range

    • setGcPressureWindow

      public void setGcPressureWindow(long windowMs)
      Sets the rolling window for GC pressure computation. Clears any active GC pressure alert and discards all recorded GC events.
      Parameters:
      windowMs - window duration in milliseconds, must be positive
      Throws:
      CacheConfigurationException - if the value is not positive

    • getMemoryThreshold

      public double getMemoryThreshold()

    • getGcDurationThreshold

      public long getGcDurationThreshold()

    • getGcPressureThreshold

      public double getGcPressureThreshold()

    • getGcPressureWindow

      public long getGcPressureWindow()

    • getGcGeneration

      public long getGcGeneration()
      Returns a monotonically increasing counter incremented on each GC event. Useful for detecting whether a GC has occurred since a previous snapshot.