Monitoring and Management Using JMX

The Java virtual machine (JVM) has built-in instrumentation that enables you to monitor and manage it using JMX.  You can also monitor instrumented applications with JMX.

• Setting System Properties for JMX
• Enabling the JMX Agent
  • Local Monitoring and Management
  • Remote Monitoring and Management
• Connecting to the JMX Agent Programmatically
• Using Password and Access Files
• JMX Management and Monitoring Properties

Setting System Properties

To enable the JMX agent and configure its operation, you must set certain system properties when you start the Java virtual machine (JVM).  You set a system property on the command-line as follows:

java -Dproperty=value ...

You can set any number of system properties in this way. If you do not specify a value, then the property is set with its default value. The full set of JMX management properties is described in Table 1. You may also set system properties in a configuration file, as described in JMX Management and Monitoring Properties.

Note: To run java (the Java VM) from the command line, you must add JRE_HOME/bin to your path, where JRE_HOME is the directory containing the Java Runtime Environment (JRE). Alternatively, you can enter the full path when you type the command.

The following documents describe the syntax and full set of command-line options supported by the Java HotSpot VMs:

• Java application launcher for Microsoft Windows
• Java application launcher for Solaris Operating Environment
• Java application launcher for Linux

Enabling the JMX Agent

To monitor a Java platform. with JMX:

1. Enable the JMX agent (the MBean server) when you start the JVM. You can enable the JMX agent for:
   • Local monitoring, for a client management application running on the local system.
   • Remote monitoring, for a client management application running on a remote system.
2. Monitor the JVM with a JMX-compliant tool such as jconsole. See Using jconsole for more information.

Local Monitoring and Management

To enable the JMX agent for local access, set this system property when you start the JVM or Java application:

com.sun.management.jmxremote

Setting this property registers the JVM instrumentation MBeans and publishes the RMI connector via a private interface to allow JMX client applications to monitor a local Java platform, that is, a JVM running on the same machine.

For example, to enable the JMX agent for the J2SE sample application Notepad:

cd JDK_HOME/demo/jfc/Notepad
java -Dcom.sun.management.jmxremote -jar Notepad.jar

where JDK_HOME is the directory where the JDK is installed.

Limitation: On Windows, for security reasons, local monitoring and management is only supported if your default Windows temporary directory is on a file system that supports setting permissions on files and directories (for example, on an NTFS file system). It is not supported on a FAT file system that provide insufficient access controls.

Using jconsole

Local monitoring with jconsole is useful for development and prototyping. Using jconsole locally is not recommended for production environments, because jconsole itself consumes significant system resources. Rather, use jconsole on a remote system to isolate it from the platform. being monitored.

Start jconsole by typing jconsole in a command shell. When you start jconsole withouth any arguments, it will automatically detect all local Java applications, and display a dialog box that enables you to select the application you want to monitor.  Both jconsole and the application must by executed by the same user name, since the monitoring and monitoring system uses the operating system's file permissions.

Note: To run jconsole from the command line, you must add JAVA_HOME/bin to your path, where JAVA_HOME is the directory containing the JDK. Alternatively, you can enter the full path when you type the command.

For more information on using jconsole, see Using jconsole.

Remote Monitoring and Management

To enable monitoring and management from remote systems, set this system property when you start the JVM:

com.sun.management.jmxremote.port=portNum

where portNum is the port number through which you want to enable JMX/RMI connections.  Be sure to specify an unused port number.  In addition to publishing a RMI connector for local access, setting this property publishes an additional RMI connector in a private read-only registry at the specified port using a well known name, "jmxrmi".

Note: You must set the above system property in addition to any properties you set for security, described below.

Remote monitoring and management requires security, to ensure that unauthorized persons cannot control or monitor your application. Password authentication over SSL (secure sockets layer) is enabled by default. You may separately disable password authentication and SSL, as described in the following sections:

• Using password authentication
• Disabling password authentication
• Using SSL
• Using client SSL authentication
• Disabling SSL
• Disabling security

After you have enabled the JMX agent for remote use, you can monitor your application using jconsole, as described in Remote Monitoring with jconsole.

Using Password Authentication

By default, when you enable the JMX agent for remote monitoring, it uses password authentication. However, the way you set it up depends on whether you are in a single-user environment or a multi-user environment.

Since passwords are stored in clear-text in the password file, it is not advisable to use your regular user name and password for monitoring. Instead, use the user names specified in the password file such as monitorRole and controlRole. For more information, see Using Password and Access Files.

Single User Environment: set up the password file in the JRE_HOME/lib/management directory as follows:

1. Copy the password template file, jmxremote.password.template, to management.jmxremote.password.
2. Set file permissions so that only the owner can read and write the password file.
3. Add passwords for roles such as monitorRole and controlRole.

Multi-user Environment: set up the password file in the JRE_HOME/lib/management directory as follows:

1. Copy the password template file, jmxremote.password.template, to your home directory.
2. Set file permissions so that only you can read and write the password file.
3. Add passwords for the roles such as monitorRole and controlRole.
4. Set this system property when you start the JVM:

   com.sun.management.jmxremote.password.file=pwFilePath

   where pwFilePath is the path to the password file.

Disabling password authentication

Password authentication for remote monitoring is enabled by default. To disable it, set the following system property when you start the JVM:

com.sun.management.jmxremote.authenticate=false

where portNum is the port number to use. Be sure to specify an unused port number.

When you disable password authentication, you can also disable SSL, as described in Disabling Security. You may also want to disable passwords, but use SSL client authentication, as described in Enabling Client SSL Authentication. 

Warning: This configuration is insecure: any remote user who knows (or guesses) your JMX port number and host name will be able monitor and control your Java application and platform. While it may be acceptable for development, it is not recommended for production systems.

Using SSL

Secure sockets layer (SSL) is enabled by default when you enable remote monitoring and management. To use SSL, you need to set up a digital certificate on the system where the JMX agent (MBean server) is running and then configure SSL properly. You use the command-line utility keytool to work with certificates. The general procedure is:

1. If you don't already have a keypair and certificate set up on the server:
   1. Generate a key pair with the keytool -genkey command.
   2. Request a signed certificate from a certificate authority (CA) with the keytool -certreq command.
   3. Import the certificate into your keystore with the keytool -import command. See Importing Certificates 
      For more information and examples, see keytool - Key and Certificate Management Tool (Solaris and Linux) (Windows).
2. Configure SSL on the server system. A full explanation of configuring and customizing SSL is beyond the scope of this document, but you generally need to set the system properties described in the following table. For more information, see Customizing the Default Key and Trust Stores, Store Types, and Store Passwords in the JSSE Guide.

For more information, see keytool - Key and Certificate Management Tool (Solaris and Linux) (Windows), and the JSSE Guide.

Enabling Client SSL Authentication

To enable client SSL authentication, set this system property when you start the JVM:

com.sun.management.jmxremote.ssl.need.client.auth=true

SSL must be enabled (the default), to use client SSL authentication.

This configuration requires the client system to have a valid digital certificate.  You must install a certificate and configure SSL on the client system, as described in Using SSL.

Disabling SSL

To disable SSL for remote monitoring, set this system property when you start the JVM:

com.sun.management.jmxremote.ssl=false

Password authentication will still be required unless you disable it, as specified in Disabling password authentication.

Disabling Security

To disable both password authentication and SSL (no security), set these system properties when you start the JVM:

com.sun.management.jmxremote.authenticate=false
com.sun.management.jmxremote.ssl=false

Warning: This configuration is insecure: any remote user who knows (or guesses) your JMX port number and host name will be able to monitor and control your Java application and platform. While it may be acceptable for development, it is not recommended for production systems.

Remote Monitoring with jconsole

1. To monitor a remote application with SSL disabled, start jconsole as follows:

   jconsole hostName:portNum

   where hostName is the name of the system running the application and portNum is the port number you specified when you started the JVM.   You can also omit the host name and port number, and enter them in the dialog box that jconsole provides.

2. To monitor a remote application with SSL enabled, you need to set up the truststore on the system where JConsole is running and configure SSL properly.

   For example, if you create a keystore as described in the JSSE Guide and start your application (Server) as follows:

   % java -Djavax.net.ssl.keyStore=keystore \
     -Djavax.net.ssl.keyStorePassword=password Server
   
   

   You need to start jconsole as follows:

   % jconsole -J-Djavax.net.ssl.trustStore=truststore \
     -J-Djavax.net.ssl.trustStorePassword=trustword
   
   

   The above configuration authenticates the server only. If client authentication is set up, you will need to provide a similar keystore for the JConsole's keys, and an appropriate truststore for the application. Please refer to Customizing the Default Key and Trust Stores, Store Types, and Store Passwords in the JSSE Guide for details.

Note: To run jconsole from the command line, you must add JAVA_HOME/bin to your path, where JAVA_HOME is the directory containing the JDK. Alternatively, you can enter the full path when you type the command.

For more information on using jconsole, see Using jconsole.

Connecting to the JMX Agent Programmatically

Once you have enabled the JMX agent, a client can use the following URL to access the service:

service:jmx:rmi:///jndi/rmi://hostName:portNum/jmxrmi

where hostName is the host name and portNum is the port number specified when the JMX agent was enabled.

A client can create a connector to the agent by instantiating an javax.management.remote.JMXServiceURL object using the URL, and then creating a connection using the JMXConnectorFactory.connect method as follows:

JMXServiceURL u = new JMXServiceURL(
  "service:jmx:rmi:///jndi/rmi:// “ + hostName + ":" + portNum +  "/jmxrmi");
  JMXConnector c = JMXConnectorFactory.connect(u); 

Using Password and Access Files

The password and access files control security for remote monitoring and management. These files are located by default in JRE_HOME/lib/management and are in the standard Java properties file format. For more information on the format, see the API reference for java.util.properties.

Password File

The password file defines the different roles and their passwords. The access control file (jmxremote.access by default) defines the allowed access for each role. To be functional, a role must have an entry in both the password and the access files.

The JRE contains a password file template named jmxremote.password.template . Copy this file to JRE_HOME/lib/management/jmxremote.password or to your home directory, and add the passwords for the roles defined in the access file.

Ensure that only the owner has read and write permissions on this file, since it contains the passwords in clear text. For security reasons, the system checks that the file is only readable or writeable by the owner and exits with an error if not. Thus in a multi-user environment, store the password file in private location such as your home directory.

Property names are roles, and the associated value is the role's password.

For example, the following are sample entries in the password file:

# The "monitorRole" role has password "QED".
# The "controlRole" role has password "R&D".
monitorRole QED
controlRole R&D

Tips: On Solaris and Linux systems, you can set the file permissions for the password file by running:

chmod 600 jmxremote.password

On Windows, see How to Secure Password File on Windows Systems

Access File

By default, the access file is named jmxremote.access. Property names are identities from the same space as the password file. The associated value must be either "readonly" or "readwrite".

The access file defines roles and their access levels. By default, the access file defines two primary roles:

• monitorRole, which grants read-only access for monitoring
• controlRole, which grants read-write access for monitoring and management.

An access control entry consists of a role name and an associated access level. The role name cannot contain spaces or tabs and must correspond to an entry in the password file. The access level is either:

• readonly: grants access to read attributes of MBeans. For monitoring, this means that a remote client in this role can read measurements but cannot perform. any action that changes the environment of the running program.
• readwrite: grants access to read and write attributes of MBeans, to invoke operations on them, and to create or remove them. This access should be granted to only trusted clients, since they can potentially interfere with the operation of an application.

A role should have only one entry in the access file. If a role has no entry, it has no access. If a role has multiple entries, then the last entry takes precedence.

Typical pre-defined roles in the access file:

# The "monitorRole" role has readonly access.
# The "controlRole" role has readwrite access.
monitorRole readonly
controlRole readwrite

JMX Management and Monitoring Properties

You can set management and monitoring properties in a configuration file or on the command line. Properties specified on the command line override properties in a configuration file. The default location for the configuration file is JRE_HOME/lib/management/management.properties, where JRE_HOME is the directory where the Java runtime environment is installed. The JVM reads this file if either of the command-line properties com.sun.management.jmxremoteor com.sun.management.jmxremote.port are set. SNMP management uses the same configuration file; for more information, see SNMP Monitoring and Management.

You can specify a different location for the configuration file with the command-line option:

com.sun.management.config.file=ConfigFilePath

where ConfigFilePath is the path to the configuration file.

The following table describes all the JMX monitoring and management properties.

Configuration Errors

If any errors occur during start up of the MBean server, the RMI registry, or the connector, the JVM will throw an exception and exit. Configuration errors include:

• Failure to bind to the port number
• Invalid password file
• Invalid access file
• Password file is readable by anyone other than the owner.

If your application runs a security manager, then additional permissions are required in the security permissions file.

Using jconsole

Jconsole is a JMX-compliant monitoring tool.  It uses the extensive JMX instrumentation of the Java virtual machine to provide information on performance and resource consumption of applications running on the Java platform.

• Starting jconsole
• The jconsole interface
• Viewing summary information
• Monitoring Memory Consumption
• Monitoring Thread Use
• Monitoring Class Loading
• Monitoring and Managing MBeans
• Viewing VM Information
• Frequently Asked Questions

Starting jconsole

The jconsole executable is in JDK_HOME/bin, where JDK_HOME is the directory where the JDK is installed.  If this directory is on your system path, you can start the tool by simply typing jconsole in a command (shell) prompt. Otherwise, you have to type the full path to the executable file.

Command Syntax

You can use jconsole to monitor both local applications (those running on the same system as jconsole) and remote applications (those running on other systems). 

Note: Using jconsole to monitor a local application is useful for development and prototyping, but is not recommended for production environments, because jconsole itself consumes significant system resources. Remote monitoring is recommended to isolate the jconsole application from the platform. being monitored.

For a complete reference on jconsole command syntax, see jconsole - Java Monitoring and Management Console.

Local Monitoring

To monitor a local application, it must be running with the same user ID as jconsole.  The command syntax to start jconsole for local monitoring is:

jconsole [processID]

where processID is the application's process ID (PID). To determine an application's PID:

• On Unix or Linux systems, use the ps command to find the PID of java.
• On Windows systems, use Task Manager to find the PID of java or javaw.

You can also use the jps command-line utility to determine PIDs.

For example, if you determined that the process ID of the Notepad application is 2956, then you would start jconsole as follows:

jconsole 2956

Both jconsole and the application must by executed by the same user name. The management and monitoring system uses the operating system's file permissions.

If  you don't specify a process ID, jconsole will automatically detect all local Java applications, and display a dialog box that lets you select the one you want to monitor (see the next section).

For more information, see Local JMX Monitoring and Management.

Remote Monitoring

To start jconsole for remote monitoring, use this command syntax:

jconsole [hostName:portNum]

where hostName is the name of the system running the application and portNum is the port number you specified when you enabled the JMX agent when you started the JVM. For more information, see Remote JMX Monitoring and Management.

If you do not specify a host name/port number combination, then jconsole will display a connection dialog box (see the next section) enabling you to enter a host name and port number.

Connecting to a JMX Agent

If you start jconsole with arguments specifying a JMX agent to which to connect, it will automatically start monitoring the specified JVM. You can connect to a different host at any time by choosing Connection | New Connection. and entering the necessary information.

Otherwise, if you do not provide any arguments when you start jconsole, the first thing you see is the connection dialog box.  This dialog box has three tabs:

• Local
• Remote
• Advanced

Local Tab

The local tab lists any JVMs running on the local system started with the same user ID as jconsole, along with their process ID and class/argument information.  Select the application you want to monitor, then click Connect.

Remote Tab

To monitor a remote JVM, enter:

• Host name: name of the machine on which the JVM is running.
• Port number: the JMX agent port number you specified when you started the JVM.
• User name and password: the user name and password to use (required only if monitoring a  JVM through a JMX agent that requires password authentication).

For information on setting the port number of the JMX agent, see Enabling the JMX Management Agent. For information on user names and passwords, seeUsing Password and Access Files.

To monitor the JVM running jconsole, simply click Connect, using host localhost and the port zero (0).

Advanced Tab

The advanced tab enables you to connect to other JMX agents (MBean servers) by specifying their JMX URL, and the user name and password.  The syntax of a JMX URL is described in the API documentation for javax.management.remote.JMXServiceURL.

Note: If the JMX agent is using in a connector which is not included in the Java platform, you need to add the connector classes to the classpath when running jconsole as follow:

jconsole -J-Djava.class.path=JAVA_HOME/lib/jconsole.jar:JAVA_HOME/lib/tools.jar:connector-path

where JAVA_HOME is the directory containing the JDK and connector-path is the directory or the jar file containing the classes not included in JDK 5.0 to be used by jconsole for connecting to a JMX agent.

The jconsole interface

The jconsole interface is composed of six tabs:

• Summary tab: displays summary information on the JVM and monitored values.
• Memory tab: displays information on memory use.
• Threads tab: displays information on thread use.
• Classes tab: displays information on class loading
• MBeans tab: displays information on MBeans
• VM tab: displays information on the JVM

The following sections provide information on each tab.

Viewing Summary Information

The Summary tab displays some key monitoring information on thread usage, memory consumption, and class loading, plus information on the JVM and operating system.

Summary

• Uptime: how long the JVM has been running
• Total compile time: the amount of time spent in just-in-time (JIT) compilation.
• Process CPU time: the total amount of CPU time consumed by the JVM

Threads

• Live threads: Current number of live daemon threads plus non-daemon threads
• Peak: Highest number of live threads since JVM started.
• Daemon threads: Current number of live daemon threads
• Total started: Total number of threads started since JVM started (including daemon, non-daemon, and terminated).

Memory

• Current heap size: Number of Kbytes currently occupied by the heap.
• Committed memory: Total amount of memory allocated for use by the heap.
• Maximum heap size: Maximum number of Kbytes occupied by the heap.
• Objects pending for finalization: Number of objects pending for finalization.
• Garbage collector information: Information on GC, including the garbage collector names, number of collections performed, and total time spent performing GC.

Classes

• Current classes loaded: Number of classes currently loaded into memory.
• Total classes loaded: Total number of classes loaded into memory since the JVM started, included those subsequently unloaded.
• Total classes unloaded: Number of classes unloaded from memory since the JVM started.

Operating System

• Total physical memory: Amount of random-access memory (RAM) that the OS has.
• Free physical memory: Amount of free RAM the OS has.
• Committed virtual memory: Amount of virtual memory guaranteed to be available to the running process.

Monitoring Memory Consumption

The Memory tab provides information on memory consumption and memory pools.

The chart shows the JVM's memory use versus time, for heap and non-heap memory, and for specific memory pools. The memory pools available depend on the JVM being used. For the HotSpot JVM, the pools are:

• Eden Space (heap): pool from which memory is initially allocated for most objects.
• Survivor Space (heap): pool containing objects that have survived GC of eden space.
• Tenured Generation (heap): pool containing objects that have existed for some time in the survivor space.
• Permanent Generation (non-heap): holds all the reflective data of the virtual machine itself, such as class and method objects. With JVMs that useclass data sharing, this generation is divided into read-only and read-write areas.
• Code Cache (non-heap): HotSpot JVM also includes a "code cache" containing memory used for compilation and storage of native code.

For more information on these memory pools, see Garbage Collection.

The Details area shows several current memory metrics:

• Used: the amount of memory currently used. Memory used includes the memory occupied by all objects including both reachable and unreachable objects.
• Committed: the amount of memory guaranteed to be available for use by the JVM. The amount of committed memory may change over time. The Java virtual machine may release memory to the system and committed could be less than the amount of memory initially allocated at startup. Committed will always be greater than or equal to used.
• Max: the maximum amount of memory that can be used for memory management. Its value may change or be undefined. A memory allocation may fail if the JVM attempts to increase the used memory to be greater than committed memory, even if the amount used is less than or equal to max (for example, when the system is low on virtual memory).

The bar chart at the lower right shows memory consumed by the memory pools in heap and non-heap memory.  The bar will turn red when the memory used exceeds the memory usage threshold.  You can set the memory usage threshold through an attribute of the MemoryMXBean.

Heap and Non-heap Memory

The JVM manages two kinds of memory: heap and non-heap memory, both created when it starts.

Heap memory is the runtime data area from which the JVM allocates memory for all class instances and arrays. The heap may be of a fixed or variable size. The garbage collector is an automatic memory management system that reclaims heap memory for objects.

Non-heap memory includes a method area shared among all threads and memory required for the internal processing or optimization for the JVM. It stores per-class structures such as a runtime constant pool, field and method data, and the code for methods and constructors. The method area is logically part of the heap but, depending on implementation, a JVM may not garbage collect or compact it. Like the heap, the method area may be of fixed or variable size. The memory for the method area does not need to be contiguous.

In addition to the method area, a JVM implementation may require memory for internal processing or optimization which also belongs to non-heap memory. For example, the JIT compiler requires memory for storing the native machine code translated from the JVM code for high performance.

Memory Pools and Memory Managers

Memory pools and memory managers are key aspects of the JVM memory system.

A memory pool represents a memory area that the JVM manages. The JVM has at least one memory pool and it may create or remove memory pools during execution. A memory pool can belong to either heap or non-heap memory.

A memory manager manages one or more memory pools. The garbage collector is a type of memory manager responsible for reclaiming memory used by unreachable objects. A JVM may have one or more memory managers. It may add or remove memory managers during execution. A memory pool can be managed by more than one memory manager.

Garbage Collection

Garbage collection (GC) is how the JVM frees memory occupied by objects that are no longer referenced. It is common to think of objects that have active references as being "alive" and un-referenced (or unreachable) objects as "dead." Garbage collection is the process of releasing memory used by the dead objects. The algorithms and parameters used by GC can have dramatic effects on performance.

The HotSpot VM garbage collector uses generational garbage collection. Generational GC takes advantage of the observation that, in practice, most programs create:

• many objects that have short lives (for example, iterators and local variables).
• some objects that have very long lifetimes (for example, high level persistent objects)

So, generational GC divides memory into several generations, and assigns each a memory pool. When a generation uses up its allotted memory, the VM performs a partial garbage collection (also called a minor collection) on that memory pool to reclaim memory used by dead objects. This partial GC is usually much faster than a full GC.

The HotSpot VM defines two generations: the young generation (sometimes called the "nursery") and the old generation. The young generation consists of an "eden space" and two "survivor spaces." The VM initially assigns all objects to the eden space, and most objects die there. When it performs a minor GC, the VM moves any remaining objects from the eden space to one of the survivor spaces. The VM moves objects that live long enough in the survivor spaces to the "tenured" space in the old generation. When the tenured generation fills up, there is a full GC that is often much slower because it involves all live objects. The permanent generation holds all the reflective data of the virtual machine itself, such as class and method objects.

The default arrangement of generations looks something like this:

As explained in the following documents, if the garbage collector has become a bottleneck, you can improve performance by customizing the generation sizes. Using jconsole, explore the sensitivity of your performance metric to the garbage collector parameters. For more information, see:

• Tuning Garbage collection with the 5.0 HotSpot VM

Monitoring Thread Use

The Threads tab provides information on thread use.

The Threads list in the lower left lists all the active threads. If you enter a string in the Filter field, the Threads list will show only those threads whose name contains the string you enter. Click on the name of a thread in the Threads list to display information about that thread to the right, including the thread name, state, and stack trace.

The chart shows the number of live threads versus time. Three lines are shown:

• Magenta: total number of threads
• Red: peak number of threads
• Blue: number of live threads.

See java.lang.Thread for more information about threads and daemon threads.

Monitoring Class Loading

The Classes tab displays information on class loading.

The graph plots the number of classes loaded versus time:

• Red line is the total number of classes loaded (including those subsequently unloaded).
• Blue line is the current number of classes loaded.

The Details section at the bottom of the tab displays the total number of classes loaded since the JVM started, the number currently loaded and the number unloaded.

Monitoring and Managing MBeans

The MBean tab displays information on all the MBeans registered with the platform. MBean server.

The tree on the left shows all the MBeans, organized according to their objectNames. When you select an MBean in the tree, its attributes, operations, notifications and other information is displayed on the right.

You can set the value of attributes, if they are writeable (the value will be displayed in blue).  You can also invoke operations displayed in the Operations tab.

Displaying a Chart

You can display a chart of an attribute's value versus time by double-clicking on the attribute value.  For example, if you click on the value of the CollectionTime property of java.lang.GarbageCollector.Copy MBean, you will see a chart that looks something like this:

Viewing VM Information

The VM tab provides information on the JVM.

The information includes:

• Uptime: Total amount of time since the JVM was started.
• Process CPU Time: Total amount of CPU time that the JVM has consumed since it was started.
• Total Compile Time: Total accumulated time spent in just-in-time (JIT) compilation. The JVM implementation determines when JIT compilation occurs. The Hotspot VM uses adaptive compilation, in which the VM launches an application using a standard interpreter, but then analyzes the code as it runs to detect performance bottlenecks, or "hot spots".