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 Zing Using JMX With 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.

Monitoring for Readiness Without Extra Dependencies

One of the factors that define if an application is ready to handle traffic or load is the number of compile queues that still need to be handled. When this value falls below a certain treshold (depending on your use case), you can consider the application to be warmed-up enough to receive traffic.

With Zing, you may want to access its proprietary MXBeans - for example, the com.azul.zing:type=Compilation MXBean - to gather runtime metrics or perform advanced monitoring. Typically, this requires you to add the relevant Zing-specific MXBean classes to your classpath to compile your code. You can find this in $JAVA_HOME/etc/extensions/mxbeans/agents/ZingJMM.jar.

However, if you build a custom load balancer (or any tool interacting with Zing) and want to avoid compile-time dependencies on Azul-specific libraries, you can use a simpler approach. Instead of importing and referencing the Zing MXBean interface directly, you can access the bean using its ObjectName:

 
ObjectName beanName = new ObjectName("com.azul.zing:type=Compilation");

With this approach, you can query and interact with the MXBean dynamically via JMX, assuming it is available at runtime. As long as Zing is started with the MXBean enabled with -XX:+UseZingMXBeans, the corresponding class will be loaded into the JVM’s internal classloader.

This is a basic example implementation to get the total outstanding compiles:

 
import java.lang.management.ManagementFactory;
import javax.management.InstanceNotFoundException;
import javax.management.MBeanServerConnection;
import javax.management.ObjectName;

public class Main {

  public static void main(String[] args) {
    MBeanServerConnection mbs = ManagementFactory.getPlatformMBeanServer();

    try {
      ObjectName beanName = new ObjectName("com.azul.zing:type=Compilation");
      Long queueDepth = (Long) mbs.getAttribute(beanName,
        "TotalOutstandingCompiles");
      System.out.println("Queue depth: " + queueDepth);
    } catch (InstanceNotFoundException e) {
      System.out.println("Not running on Zing,"
        + " or running Zing without -XX:+UseZingMXBeans");
    } catch (Exception e) {
      // something else is wrong, this is unexpected
      e.printStackTrace();
    }
  }
}

This is a more extended example that shows the time needed to reach an empty compile queue:

 
import java.lang.management.*;
import javax.management.*;

/**
 * A utility for Azul Zing JVMs, useful for awaiting the draining of JIT compilation
 * queues at program start. This utility may be used by e.g. startup or readiness
 * probes to have code better optimized before traffic actually starts.
 *
 * compileQueueDepthOrDeadlineReached(targetDepth, deadlineSinceStartMs)
 *   → true  if  (TotalOutstandingCompiles ≤ targetDepth) OR
 *              (uptime ≥ deadlineSinceStartMs)
 *   → false otherwise.
 *
 * The demo main() can be used as an example.
 */
public final class ZingAwaitCompilationsOnStart {

    private static final long JVM_START =
            ManagementFactory.getRuntimeMXBean().getStartTime();

    private static final MBeanServer MBS =
            ManagementFactory.getPlatformMBeanServer();

    private static final boolean IS_ZING =
            System.getProperty("java.vm.name", "")
                .toLowerCase().contains("zing");

    private static final ObjectName COMPILATION_OBJECTNAME;
    private static final boolean   COMPILATION_MXBEAN_AVAILABLE;

    static {
        ObjectName objectName = null;
        boolean    mxbeanAvailable = false;

        if (IS_ZING) {
            try {
                objectName = new ObjectName("com.azul.zing:type=Compilation");
                mxbeanAvailable = MBS.isRegistered(objectName);
            } catch (MalformedObjectNameException e) {
                e.printStackTrace(System.err);
            }
        }
        COMPILATION_OBJECTNAME       = objectName;
        COMPILATION_MXBEAN_AVAILABLE = mxbeanAvailable;
    }

    private ZingAwaitCompilationsOnStart() {}

    /**
     * @param targetDepth               queue size (inclusive) that satisfies the condition
     * @param deadlineSinceStartMs      absolute deadline counted from JVM start (ms)
     * @param awaitDeadlineOnlyOnZing   true → on non-Zing JVMs return <code>true</code> immediately
     */
    public static boolean compileQueueDepthOrDeadlineReached(int targetDepth,
                                                             long deadlineSinceStartMs,
                                                             boolean awaitDeadlineOnlyOnZing) {

        if (System.currentTimeMillis() - JVM_START >= deadlineSinceStartMs) {
            return true;
        }

        if (!IS_ZING) {
            return awaitDeadlineOnlyOnZing;   // if true, succeed immediately on non-Zing
        }
        if (!COMPILATION_MXBEAN_AVAILABLE) {
            return false;
        }

        try {
            long outstandingCompiles = ((Number) MBS.getAttribute(
                    COMPILATION_OBJECTNAME, "TotalOutstandingCompiles")).longValue();
            return outstandingCompiles <= targetDepth;
        } catch (Exception e) {
            return false;
        }
    }

    public static void main(String[] args) {
        int  targetDepth = 0;        // wait until the queue empties
        long deadlineMs  = 120_000;  // 120 s from JVM start

        long startSinceStart = System.currentTimeMillis() - JVM_START;
        System.out.println("Await loop started at JVM-uptime(ms): "
            + startSinceStart);

        while (!compileQueueDepthOrDeadlineReached(targetDepth, deadlineMs, true)) {
            try { Thread.sleep(1); }
            catch (InterruptedException ie) {
                Thread.currentThread().interrupt();
                return;
            }
        }

        long endSinceStart = System.currentTimeMillis() - JVM_START;
        System.out.println("Condition met at JVM-uptime(ms): "
            + endSinceStart);
    }
}