Updated Nov 14, 2007 by vmatters
Labels:	Featured

BroadwayAndJavaManagement

Broadway and the Java Management Architecture

Starting with version 5, Java introduced inherent features to support VM instrumentation for runtime management. Using JMX as its underlying technology stack, this feature exposes a rich set of runtime information made available through specialized management beans called MXBeans. These beans provide a full profile of the the JVM at runtime exposing a range of data from system OS information, to memory consumption, to deadlock detection. This wiki shows how Broadway can be used to leverage this instrumented data to monitor the VM memory consumption at runtime.

Detecting High Memory Usage

This simple example illustrates how one would use Broadway with the Java Management infrastructure to detect high memory usage and react to it. Here, the code takes advantage of the instrumentation provided by the MemoryMXBean to read available memory at runtime. This management bean exposes heap and non-heap memory information as it changes over time. For instance, the call to MemoryMXBean.getHeapMemoryUsage().getMax() will return the maximum amount of heap memory that the VM can use. Request to use more than that amount will result in an OutOfMemoryError.

So, suppose you are writing a program that consumes large chunks of memory. You can setup Broadway to monitor your memory usage and react to it. For the sake of demonstration, this example uses a class that creates memory leak to eventually consume all available memory over time. The example shows how one can write a monitoring expression to react to memory consumption when the available memory is at, say 90% capacity. We will skip the details of Broadway components setup here, you can get more info at BroadwayJavaTutorial.

Setting Up

In the constructor, all necessary Broadway components are wired together. Note that Java's Management API supports factory classes that make it easy to get access to the different management beans. Here, the code uses ManagementFactory.getMemoryMXBean() to get an instance of the MemoryMXBean. The rest of the code is pretty self-explanatory.

    
    private BeanMonitor monitor;
    private ScriptedAction action; 
    private MappedResourceCollector resources;
    MemoryMXBean memBean;
    
    ...
    
	public OutOfMemMonitor() {
        ...
		monitor = new BeanMonitor();
		action = new ScriptedAction("scripts/MemMonitor.groovy");
		resources = new MappedResourceCollector();
		memBean = ManagementFactory.getMemoryMXBean();
        ...
	}

See full listing of code OutOfMemMonitor

Monitoring Expression

The monitor expression tests whether memory consumption is within 90% capacity or above. To achieve this, the code does three things:

An instance of MemoryMXBean is added to the resources map for reference in the monitor expression script. This is not necessary but, it eliminates the need to add additional import statements in the script.
The monitor expression calculates the percentage of memory used by casting the retrieved memory values to double (they are long). This is necessary to get better precision when the percentage used (pcntMemUsed) is calculated.
Finally, the condition is tested by comparing the calculated percentage used to 0.90.

    
    resources.putResource("memBean", memBean);

    monitor.setMonitorExpression(
        "def maxMem   = (double)params.memBean.getHeapMemoryUsage().getMax();" +
        "def usedMem  = (double)params.memBean.getHeapMemoryUsage().getUsed();" +
        "def pcntUsed = usedMem/maxMem;" +
        "params.pcntMemUsed = pcntUsed;" +
        " pcntUsed >= 0.90 "
    );

NOTE: This last statement is returned to the monitor object as a boolean to determine whether to run the script file scripts/MemMonitor.groovy (see above).

See full listing of code OutOfMemMonitor

The Action

The action specified for the monitor is a ScriptedAction. It executes script script/MemMonitor.groovy which, for this purpose, does not do much. It simply logs the fact that the VM is within its red zone and is running out of memory. But, this can be expanded to accomplish other tasks such as notification or even request for garbage collection.

    
println ("Processing is running out of memory... usage at $resources.pcntMemUsed %");

// call gc after a while
if(resources.pcntMemUsed > 0.95) {
    println ("Calling garbage collector...");
    $resources.memBean.gc();
}

Conclusion

The example illustrated here shows how the Java Management architecture can be paired with Broadway for monitoring VM internal states. Here a Broadway monitor expression is used to detect when memory consumption within 90 percent of capacity. It should be noted that monitoring memory is designed for features such as load balancing and not to recover from out of memory faults.