Azul Platform Prime MXBeans

Introduction

Azul Platform Prime MXBeans provide an interface to answer detailed questions about the behavior of your application and the Azul Zing Builds of OpenJDK (Zing). The MXBeans are designed for both monitoring performance and extracting the low level details to discover the root causes of problems. To use Azul Platform Prime MXBeans, you will need to use the command-line option:

 
-XX:+UseZingMXBeans

In order to compile code that relies on the use of Azul Platform Prime MXBeans, you will need to add the command line option to Zing javac command:

 
-J-XX:+UseZingMXBeans

You can compile code that relies on Azul Platform Prime MXBeans with a javac from another vendor. However, you will need to add the ZingJMM.jar file to the classpath. For example:

 
javac -cp $(ZINGMXBEANSJMMJARFULLPATH) $(JAVA_SOURCE_FILES)

Where the ZingJMM.jar file is at the following location, but can be copied to any convenient location for building your application:

 
$JAVA_HOME/etc/extensions/mxbeans/agents/ZingJMM.jar

Note that Azul Platform Prime MXBeans .jar file should not be added to the CLASSPATH variable. Otherwise, ZingMXBeans methods return an exception when called.

A program that is able to access the MXBeans and graph the collected metrics, such as JConsole, will aid in your ability to quickly understand the interfaces and their use. The available MXBean operations provide control of both the data collection and the JVM behavior.

See ZingGCReporter for details of using Azul Platform Prime MXBeans when running on Zing.

Note that you might get an error message when permissions are insufficient to access the MBean server. If that’s the case, you will need to create or update a ~/.java.policy file and add the required permissions to it (see table below). When using a .java.policy file, ensure that you have an entry policy.url.2=file:${user.home}/.java.policy in the $JAVA_HOME/jre/lib/security/java.security file.

Azul Platform Prime MXBeans provide the interfaces that enable you to get the answers you need to understand your application’s performance. Flexibility in the management of the values stored as peak values and those available in accumulators makes it easy to tailor the collection of the data for efficiency and effectiveness.

Azul Platform Prime MXBeans Interfaces

The Azul Platform Prime MXBeans in the table below are classified by their interface functionality.

Azul Platform Prime MXBeans Classes

The Azul Platform Prime MXBeans classes are listed in the table below.

Azul Platform Prime MXBeans Enums

The Azul Platform Prime MXBeans enumerations are listed in the table below.

Refer to the Azul Platform Prime MXBeans javadoc for more information about the MXBeans APIs.

Monitoring the Zing Using JMX and Azul Platform Prime MXBeans

For those cases where you want to monitor Zing in addition to monitoring the application, use Azul Platform Prime MXBeans.

Primarily, the following are of interest for Zing monitoring:

For accessing the values for each of these attributes over time, use any JMX-capable systems monitoring tool or $JAVA_HOME/bin/jconsole. In JConsole, use the entries in its MBeans tab to access the Azul Platform Prime MXBeans and get a quick overview.

Java Heap Memory Use

Monitoring memory use is helpful to detect memory leaks or to collect statistics about the general memory use by an application. The latter can be used to correctly size the Java heap to be consistent with the application’s memory requirements.

MXBean: com.azul.zing → Memory → Attributes:

MXBean: java.lang → Memory → Attributes:

Garbage Collector Activity

Monitoring garbage collector activity is useful for capacity planning. For instance, the activity level can be used to determine the CPU resources required to process varying application object allocation rates. Because that object allocation rate is proportional to the amount of work done by the application, the garbage collector activity can be used to determine maximum application workloads. Naturally, the Java heap size is related to garbage collector activity. Increasing the Java heap size can reduce the impact of sudden high garbage collector activity and the underlying high workloads. The latter are also seen as allocation rate spikes.

MXBean: com.azul.zing → GarbageCollector → GPGC New → Attributes:

MXBean: com.azul.zing → GarbageCollector → GPGC Old → Attributes:

If you need more fine-granular monitoring, the following additional attributes provide more precise information about the garbage collectors’ behavior:

MXBean: com.azul.zing → Time → Attributes:

Code Cache Memory Use

MXBean: com.azul.zing > MemoryPool > CodeCache → Attributes:

Configuration

To activate the JMX connector on Zing and enable the Azul Platform Prime specific MXBeans, add the following command line parameters and configure them according to your system’s requirements (port and security options):

 
-XX:+UseZingMXBeans
-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=9001
-Dcom.sun.management.jmxremote.local.only=false
-Dcom.sun.management.jmxremote.authenticate=true
-Dcom.sun.management.jmxremote.password.file=passwordFile
-Dcom.sun.management.jmxremote.ssl=false

The passwordFile contains two lines with username and associated password for read only access to attributes (monitorRole) and read/write access to methods and user functions (controlRole). Only change the passwords, not the usernames! Example:

 
monitorRole password1 controlRole password2

File permission to the passwordFile needs to be limited:

 
chmod og-rwx passwordFile

To avoid connection failures over the JMX protocol on systems with multiple network interfaces or to connect to a container system, it is often needed to specify the RMI hostname and RMI port:

 
-Djava.rmi.server.hostname=HOSTNAME
-Dcom.sun.management.jmxremote.rmi.port=9001

Where:

To improve security, please enable com.sun.management.jmxremote.ssl=true.