Using JConsole

JConsole (Java™ Monitoring and Management Console) is a graphical tool that allows the user to monitor and manage the behavior of Java applications.

Note: Because JConsole consumes significant system resources, Oracle recommend its use only in development environments for creating prototypes. Remote monitoring is also recommended to isolate the JConsole application from the platform being monitored.

The JConsole tool is built on the java.lang.management API. JConsole connects to applications that run on the same workstation or on a remote workstation. The applications must be configured to allow access.

When JConsole connects to a Java application, it reports information about the application. The details include memory usage, the running threads, and the loaded classes. This data helps you monitor the behavior of your application and the JVM. The information is useful in understanding performance problems, memory usage issues, hangs, or deadlocks.

Setting up JConsole to monitor a Java application

The Java application that you want to monitor must be started with command-line options that make it accessible to JConsole from other systems or other users. JConsole can attach to processes owned by the same user on the same system without these options. The simplest set of options for monitoring are shown in the following example:
```
-Dcom.sun.management.jmxremote.port=<port number>
-Dcom.sun.management.jmxremote.authenticate=false
-Dcom.sun.management.jmxremote.ssl=false
```
The value for <port number> must be a free port on your system. In this example, the authenticate and ssl options prevent password authentication and encryption by using Secure Sockets Layer (SSL). Using these options allows JConsole, or any other JMX agent, to connect to your Java application if it has access to the specified port. Use these non-secure options only in a development or testing environment. For more information about configuring security options, see https://docs.oracle.com/javase/8/docs/technotes/guides/jmx/overview/connectors.html.
Start JConsole by typing jconsole on the command line. Your path must contain the bin directory of a Java installation.
The JConsole New Connection dialog opens: Enter the host name and port number that you specified in step 1. If you are running JConsole on the same workstation as your Java application, leave the host name value as localhost. For a remote system, set the host field value to the host name or IP address of the workstation. Leave the Username and Password fields blank if you used the options specified in step 1.
Click connect. JConsole starts and displays the Summary tab.

Setting up JConsole to monitor itself

JConsole can monitor itself. This ability is useful for simple troubleshooting of the Java environment.

Start JConsole by typing jconsole on the command line. Your path must contain the bin directory of the SDK.
The JConsole New Connection dialog opens: Enter localhost:0 in the Remote Process field.
Click connect. JConsole starts and displays the summary tab.

Using JConsole to monitor a Java application

The JConsole Summary tab shows key details about the connected JVM. From here, you can select any of the other tabs for more details on a particular aspect. The Memory tab shows a history of usage of each memory pool in the JVM, – the most useful being the heap memory usage.

You can also request that a garbage collection is carried out by clicking the Perform GC button. You must be connected with security options disabled as described previously, or be authenticated as a control user.

The Threads tab shows the number of threads currently running and a list of their IDs.

Clicking a thread ID shows the thread state and its current stack trace.

The Classes tab displays the current number of loaded classes and the number of classes loaded and unloaded since the application was started. Selecting the verbose output check box allows verbose class loading output to be switched on and off to see a list of classes that are loaded in the client JVM. The output is displayed on the stderr output of the client JVM.

The MBeans tab allows you to inspect the state of the platform MBeans, which provides more detail about the JVM. For more information about MBeans and J9 MXBean extensions, see the Language management interface section of the Eclipse OpenJ9 documentation.

Finally, the VM tab gives information about the environment in which your Java application is running, including any JVM arguments and the current class path.

Troubleshooting JConsole

JConsole is a Swing application. Running JConsole on the same workstation as the Java application you want to monitor affects the performance of your Java application. You can use JConsole to connect to a JVM running on a remote workstation to reduce the effect on application performance.

Because JConsole is a Java application, you can pass it Java command-line options through the application that starts JConsole by prefixing them with –J. For example, to change the maximum heap size that JConsole uses, add the command-line option -J-Xmx<size>.

JConsole uses the Attach API to connect to an application and can connect only to other J9 virtual machines. If you experience problems when using JConsole to monitor a remote application, the root cause might be the Attach API. To diagnose problems, see Java Attach API.

Known Limitations

Using the local process list: The local process list does not work. Use localhost:<port> in the Remote Process text entry field to connect to a local JVM.
CPU usage in the Overview tab: The CPU usage display does not work.

Further information

More details about JConsole and the definitions of the values that are displayed, see https://docs.oracle.com/javase/8/docs/technotes/guides/management/index.html in the Oracle documentation.