Back to Zing Documentation Home

Zing MXBeans

See https://docs.azul.com/zing/ZingMXBeans_javadoc/ for complete summaries of interfaces, classes, methods, descriptions of parameters and return values generated from the source code.

Introduction

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

-XX:+UseZingMXBeans

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

-J-XX:+UseZingMXBeans

You can compile code that relies on Zing 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 Zing 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 Zing MXBeans when running on a Zing JVM.

Note that your might get an error message when permissions are insufficient to access the MBean server. If that's the case, you will need ti create of update a ~/.java.policy file and add the required permissions to it (see also Interface MBeanServer). If 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.

Zing 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.

The sections below describe the Zing MXBeans categorized by:

Zing MXBeans Interfaces

The Zing MXBeans in the table below are classified by their interface functionality.

Interface Summary Interface Description
GarbageCollectorMXBean

GarbageCollectorMXBean is an interface used by the management system to access garbage collector properties and reset the values of associated counter and accumulator properties.

MemoryManagerMXBean

MemoryManagerMXBean is an interface used by the management system to access memory manager properties.

MemoryMXBean

MemoryMXBean is an interface used by the management system to access memory-related properties. The MemoryMXBean interface is the easiest to use to answer your questions about Java heap use and performance.

MemoryPoolMXBean

MemoryPoolMXBean is an interface used by the management system to access memory pool properties.

PersistentProfileMXBean

PersistentProfileMXBean provides access to the reporting capabilities of ReadyNow! profile logs.

TimeMXBean

Time provides the elapsed time since the launch of the Zing virtual machine and the clock time in milliseconds at the launch of the Zing virtual machine.

Zing MXBeans Classes

The Zing MXBeans classes are listed in the table below.

Class Summary Class Description
GarbageCollectorNotificationInfo Garbage collector notification information.
GCDetails

A snapshot of the details of the JVM environment before and after a garbage collection.

ManagementFactory

The factory for retrieving all managed objects for the JVM as well as the JVM’s MBean server.

ManagementPermission

A SecurityPermission for use with the management system.

MemoryNotificationInfo

Memory notification information.

MemoryPoolNotificationInfo Memory pool notification information.
MemoryUsage

A memory pool usage snapshot with sizes and the time the snapshot was taken.

PauseDetails

A PauseDetails object represents a pause event impacting all the threads in a running Java virtual machine and includes a timestamp specifying the time since the launch of the Java virtual machine process, the duration of the pause, and the reason for the pause (plus additional, optional, very detailed information).

Zing MXBeans Enums

The Zing MXBeans enumerations are listed in the table below.

Class Summary Class Description
MemoryPoolSizeType

For each memory pool: Characteristic of its size: FIXED or ELASTIC; otherwise: UNINITIALIZED.

MemoryType

For each memory pool: in the ZVM process: JAVA_HEAP or NON_JAVA_HEAP; for system memory: SYSTEM.

Refer to the Zing MXBeans javadoc for more information about the MXBeans APIs.

Monitoring the ZVM Using JMX and Zing MXBeans

For those cases where you want to monitor the ZVM in addition to monitoring the application, use Zing MX Beans.

Primarily, the following are of interest for ZVM monitoring:

  • Java heap memory use
  • Garbage collector activity: concurrent GC time and application stopped time

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 Zing 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:

  • PercentJavaHeapOccupiedAfterCollection: The percentage of the heap in use after each garbage collection. The returned value is equivalent to the application's current minimum memory requirement. It can also be used to detect memory leaks because consistently increasing values after full garbage collections create an easily seen pattern. It's useful to set a warning threshold that triggers an alarm if the value exceeds 70% over a 5 minute interval (though this threshold value depends on the live set size in use by your application). The value includes the memory in use for the Permanent Generation, a memory pool in the ZVM’s Java heap.
  • ApplicationObjectHeapUse and ApplicationObjectHeapUsableMemory: The process’s current memory use and the total size of the application object area of the Java heap. The returned heap use value represents the current memory use of the New (also called Young) Generation together with the current memory use of the Old Generation. This metric is a refinement of the PercentJavaHeapOccupiedAfterCollection that removes some of the guesswork about the contributions of the other memory pools in the ZVM’s Java heap to the application’s Java heap memory use.

 

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

  • CurrentUse: Use of the memory pool where JIT compiled code is stored. Useful to decide whether increasing the size of the code cache using -XX:ReservedCodeCacheSize=N (default value is 256 MB) is needed.
  • CurrentSize: Value returned is the maximum size of the code cache. The value can be set by using -XX:ReservedCodeCacheSize=N (default value is 256 MB).

 

MXBean: java.lang -> Memory -> Attributes:

  • HeapMemoryUsage (init, used, committed, max). Used for monitoring memory use by JVMs. For JVMs other than Zing, setting notification thresholds can help monitor the JVM and application’s use of system resources. When using the ZVM, the Java heap use between collections varies between a minimum of the live set size and 100% (or more). In other words, the ZVM attempts to use a much of the Java heap as possible. Doing so extends the time between collections and lowers the ZVM garbage collector’s overhead. Using a maximum use notification threshold value when running an application with the ZVM that is less than 100% will result in spurious notifications.

 

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:

  • PercentageOfTimeCollectorIsRunning: The ratio of the "garbage collection time" to the "interval between end times of two consecutive collections.” The value is based on the most recent garbage collection and is not cumulative. The percentages are calculated separately for the New Generation collector and the Old Generation collector. A warning threshold of 30% over 5 minutes should be set to warn about over-use of available CPU resources by the garbage collector. This is most important metric for monitoring the ZVM’s garbage collector behavior because this metric is the first to increase in situations when the system's capacity is nearing its limits.

 

MXBean: com.azul.zing -> GarbageCollector -> GPGC Old -> Attributes:

  • PercentageOfTimeCollectorIsRunning: The same recommendations as for the New Generation collector, but for the Old Generation collector. Use the same threshold to monitor. The time for processing Permanent Generation objects is included in this metric.

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

  • CollectorCumulativePauseTimeSec: Cumulative garbage collector pause time. The typical length of time for each of these ZVM pauses is in the range of single digit milliseconds or less.
  • CollectorCumulativeRunningTimeSec: Cumulative wall clock time the ZVM’s garbage collector has been running in parallel with the application’s threads. During this time, more CPU resources are used because the garbage collector is running its own set of threads. The number of running garbage collector threads (for each of the New Generation collector and Old Generation collector) is based on the number of CPU threads (hyper-threads or just physical cores if the machine is configured with hyper-threading off).
  • CollectionCount: Cumulative number of garbage collections since ZVM start.

 

MXBean: com.azul.zing -> Time -> Attributes:

  • ElapsedTimeSinceJVMStartSec: Seconds since ZVM start. Useful for time-base calculations with CollectorCumulativePauseTimeSec and CollectorCumulativeRunningTimeSec.

Configuration

To activate the JMX connector on the ZVM and enable the Zing 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

On systems with multiple network interfaces it is sometimes needed to specify the hostname of the server where Zing is running: -Djava.rmi.server.hostname=HOSTNAME

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


© Azul Systems, Inc. 2020 All rights reserved.

Privacy Policy | Legal | Terms of Use