3 Using JConsole

The JConsole graphical user interface is a monitoring tool that complies with the Java Management Extensions (JMX) specification. JConsole uses the extensive instrumentation of the Java Virtual Machine (Java VM) to provide information about the performance and resource consumption of applications running on the Java platform.

JConsole has been updated to present the look and feel of the Windows and GNOME desktops (other platforms will present the standard Java graphical look and feel). The screen captures presented in this document are taken from an instance of the interface running on Windows XP.

Starting JConsole

The jconsole executable file can be found in JDK_HOME/bin, where JDK_HOME is the directory in which the Java Development Kit (JDK) is installed. If this directory is in your system path, then you can start JConsole by simply entering jconsole in a command (shell) prompt. Otherwise, you have to enter the full path to the executable file.

Command Syntax

You can use JConsole to monitor both local applications, namely those running on the same system as JConsole, as well as remote applications, namely those running on other systems.

Note:

Using JConsole to monitor a local application is useful for development and for creating prototypes, 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.

See jconsole in the Java Development Kit Tool Specifications for the complete syntax.

Setting Up Local Monitoring

Start JConsole using the following command:

% jconsole

When JConsole starts, select the required Java applications running locally that JConsole can connect to.

If you want to monitor a specific application, and you know that application's process ID, then start JConsole so that it connects to that application. This application must be running with the same user ID as JConsole. Use the following command syntax to start JConsole for local monitoring of a specific application:

% jconsole processID

processID is the application's process ID (PID). You can determine an application's PID in the following ways:

• On Linux or macOS systems, you can use the ps command to find the PID of the java instance that is running.

• On Windows systems, you can use the Task Manager to find the PID of java or javaw.

• You can also use the jps command-line utility to determine PIDs. See jps in Java Development Kit Tool Specifications.

For example, if the process ID of the Notepad application is 2956, then start JConsole with the following command:

% jconsole 2956

Both JConsole and the application must by executed by the same user. The management and monitoring system uses the operating system's file permissions. If you do not specify a process ID, JConsole will automatically detect all local Java applications, and display a dialog box that lets you select which one you want to monitor (see Connecting to a JMX Agent).

See Local Monitoring and Management.

Setting Up Remote Monitoring

To start JConsole for remote monitoring, use the following command syntax:

% jconsole hostName:portNum

The hostName is the name of the system running the application and portNum is the port number you specified when you enabled the JMX agent while starting the Java VM. See Remote Monitoring and Management.

If you do not specify a host name/port number combination, then JConsole will display a connection dialog box (Connecting to a JMX Agent) to enable you to enter a host name and port number.

Setting Up Secure Remote Monitoring

You can also start JConsole so that monitoring will be performed over a connection that is secured using Secure Sockets Layer (SSL). See Remote Monitoring with JConsole with SSL Enabled for the command to start JConsole with a secure connection.

Connecting to a JMX Agent

If you start JConsole with arguments specifying a JMX agent to connect to, then it will automatically start monitoring the specified Java VM. You can connect to a different host at any time by selecting Connection and New Connection, and entering the necessary information.

Otherwise, if you do not provide any arguments when you start JConsole, then the first thing that you see is the connection dialog box. This dialog box has two options, allowing connections to either Local or Remote processes.

Connecting JConsole to a Local Process

If you start JConsole without providing a specific JMX agent to connect to, then you will see the following dialog box:

Figure 3-1 Creating a Connection to a Local Process

The Local Process option lists any Java VMs running on the local system that were started with the same user ID as JConsole, along with their process ID and their class or argument information. To connect JConsole to your application, select the application that you want to monitor, then click Connect. The list of local processes includes applications running in the following types of Java VM:

• Applications with the management agent enabled: These include applications on the Java SE platform that were started with the -Dcom.sun.management.jmxremote option or with the -Dcom.sun.management.jmxremote.port option specified. In addition, the list also includes any applications that were started on the Java SE platform without any management properties, but are attached to by JConsole, which enables the management agent at runtime.

• Applications that are attachable, with the management agent disabled: These include an attachable application that supports loading of the management agent at runtime. Attachable applications include applications that are started on the Java SE platform, which support the Attach API. Applications that support dynamic attach do not require the management agent to be started by specifying the com.sun.management.jmxremote or com.sun.management.jmxremote.port options at the command line. JConsole does not need to connect to the management agent before the application is started. If you select this application, then a note is displayed on screen that the management agent will be enabled when the connection is made. In the example, connection dialog box that is shown in Figure 3-1, the NetBeans IDE and JConsole are started within a Java SE platform VM. Both appear in normal text, meaning that JConsole can connect to them. In Figure 3-1, JConsole is selected and the note is visible.

• Applications that are not attachable, with the management agent disabled: These include applications started on a Java SE platform without the -Dcom.sun.management.jmxremote or com.sun.management.jmxremote.port options. These applications appear grayed-out in the table and JConsole cannot connect to them. In the example connection dialog box shown in Figure 3-1, the Anagrams application was started with a Java SE platform VM without any of the management properties to enable the JMX agent, and consequently shows up in gray and cannot be selected.

Figure 3-2 Attempting to Connect to an Application Without the Management Agent Enabled

In the example connection dialog box shown in Figure 3-2, you can see that the Anagrams application is selected, but Connect remains grayed-out, and a note has appeared informing you that the management agent is not enabled for this process. JConsole cannot connect to Anagrams because it was not started with the correct Java VM or with the correct options.

Connecting JConsole to a Remote Process

When the connection dialog box opens, you are also given the option of connecting to a remote process.

Figure 3-3 Creating a Connection to a Remote Process

To monitor a process running on a remote Java VM, you must provide the following information:

• Host name: The name of the machine on which the Java VM is running.

• Port number: The JMX agent port number you specified when you started the Java VM.

• User name and password: The user name and password to use (required only if monitoring a Java VM through a JMX agent that requires password authentication).

To set the port number of the JMX agent, see Enabling the Ready-to-Use Management.

See Using Password and Access Files.

To monitor the Java VM that is running JConsole, click Connect and enter host as localhost and the port 0.

Connecting Using a JMX Service URL

You can also use the Remote Process option to connect to other JMX agents by specifying their JMX service URL, and the user name and password. The syntax of a JMX service URL requires that you provide the transport protocol used to make the connection, as well as a service access point. The full syntax for a JMX service URL is described in the API documentation for javax.management.remote.JMXServiceURL.

Figure 3-4 Connecting to a JMX Agent Using the JMX Service URL

If the JMX agent uses a connector that is not included in the Java platform, then you must add the connector classes to the class path when you run the jconsole command, as follows:

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

connector-path is the directory or the Java archive (JAR) file containing the connector classes that are not included in the JDK, to be used by JConsole.

Presenting the JConsole Tabs

After you have connected JConsole to an application, JConsole displays the following six tabs:

• Overview: Displays overview information about the Java VM and monitored values

• Memory: Displays information about memory use

• Threads: Displays information about thread use

• Classes: Displays information about class loading

• VM: Displays information about the Java VM

• MBeans: Displays information about MBeans

Use the green connection status icon in the upper right-hand corner of JConsole to disconnect from or reconnect to a running Java VM. You can connect to any number of running Java VMs at a time by selecting Connection, then New Connection from the drop-down menu.

Viewing Overview Information

The Overview tab displays graphical monitoring information about CPU usage, memory usage, thread counts, and the classes loaded in the Java VM, all in a single screen.

Figure 3-5 Overview Tab

The Overview tab provides an easy way to correlate information that was previously available only by switching between multiple tabs.

Saving Chart Data

JConsole allows you to save the data presented in the charts in a comma-separated values (CSV) file. To save data from a chart, right-click on any chart, select Save data as..., and then specify the file in which the data will be saved. You can save the data from any of the charts displayed in any of JConsole's different tabs in this way.

The CSV format is commonly used for data exchange between spreadsheet applications. The CSV file can be imported into spreadsheet applications and can be used to create diagrams in these applications. The data is presented as two or more named columns, where the first column represents the time stamps. After importing the file into a spreadsheet application, you will usually need to select the first column and change its format to be date or date/time as appropriate.

Monitoring Memory Consumption

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

Figure 3-6 Memory Tab

Click Perform GC in the Memory tab to perform garbage collection whenever you want. The chart shows the memory use of the Java VM over time, for heap and nonheap memory, as well as for specific memory pools. The memory pools available depend on the version of the Java VM being used. For the HotSpot Java VM, the memory pools for serial garbage collection are the following:

• Eden Space (heap): The pool from which memory is initially allocated for most objects.

• Survivor Space (heap): The pool containing objects that have survived the garbage collection of the Eden space.

• Tenured Generation (heap): The pool containing objects that have existed for some time in the survivor space.

• Permanent Generation (nonheap): The pool containing all the reflective data of the virtual machine itself, such as class and method objects. With Java VMs that use class data sharing, this generation is divided into read-only and read/write areas.

• Code Cache (nonheap): The HotSpot Java VM also includes a code cache, containing memory that is used for compilation and storage of native code.

You can display different charts for charting the consumption of these memory pools by selecting the required options in the Chart drop-down menu. Also, clicking either the Heap or Nonheap bar charts in the bottom right-hand corner will switch the chart displayed. Finally, you can specify the time range over which you track memory usage, by selecting the required options in the Time Range drop-down menu.

See Garbage Collection.

The Details area shows several current memory metrics:

• Used: The amount of memory currently used, including the memory occupied by all objects, both reachable and unreachable.

• Committed: The amount of memory guaranteed to be available for use by the Java VM. The amount of committed memory may change over time. The Java virtual machine may release memory to the system and the amount of committed memory could be less than the amount of memory initially allocated at startup. The amount of committed memory will always be greater than or equal to the amount of used memory.

• 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 Java VM 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).

• GC time: The cumulative time spent on garbage collection and the total number of calls. It may have multiple rows, each of which represents one garbage collector algorithm used in the Java VM.

The bar chart on the lower right-hand side shows the memory consumed by the memory pools in heap and nonheap 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 Nonheap Memory

The Java VM manages two kinds of memory: heap and nonheap memory, both of which are created when the Java VM starts.

• Heap memory: Is the runtime data area from which the Java VM 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.

• Nonheap memory: Includes a method area shared among all threads and memory required for the internal processing or optimization for the Java VM. 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 the implementation, a Java VM may not garbage collect or compact it. Like the heap memory, the method area may be of a fixed or variable size. The memory for the method area does not need to be contiguous.

In addition to the method area, a Java VM may require memory for internal processing or optimization, which also belongs to nonheap memory. For example, the Just-In-Time (JIT) compiler requires memory for storing the native machine code translated from the Java VM code for high performance.

Memory Pools and Memory Managers

Memory pools and memory managers are key aspects of the Java VM's memory system.

• Memory pool: Represents a memory area that the Java VM manages. The Java VM has at least one memory pool and it may create or remove memory pools during execution. A memory pool can belong either to heap or to nonheap memory.

• 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 Java VM 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 Java VM frees memory occupied by objects that are no longer referenced. It is common to think of objects that have active references as being live and nonreferenced (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 Java HotSpot VM garbage collector uses generational GC. Generational GC takes advantage of the observation that most programs conform to the following generalizations:

• They create many objects that have short lives, for example, iterators and local variables.

• They create some objects that have very long lives, for example, high-level persistent objects.

Generational GC divides memory into several generations, and assigns one or more memory pools to each. When a generation uses up its allotted memory, the VM performs a partial GC (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 Java 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 Figure 3-7.

Figure 3-7 Generations of Data in Garbage Collection

If the garbage collector has become a bottleneck, then you can improve performance by customizing the generation sizes. Using JConsole, you can investigate the sensitivity of your performance metric by experimenting with the garbage collector parameters. See Performance Considerations in Java Platform, Standard Edition HotSpot Virtual Machine Garbage Collection Tuning Guide.

Monitoring Thread Use

The Threads tab provides information about thread use.

Figure 3-8 Threads Tab

The Threads list in the lower left corner lists all the active threads. If you enter a string in the Filter field, then the Threads list will show only those threads whose name contains the string that you entered. Click 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 over time. Two lines are shown:

• Red: Peak number of threads

• Blue: Number of live threads

The Threading MXBean provides several other useful operations that are not covered by the Threads tab.

• findMonitorDeadlockedThreads: Detects if any threads are deadlocked on the object monitor locks. This operation returns an array of deadlocked thread IDs.

• getThreadInfo: Returns the thread information. This includes the name, stack trace, and the monitor lock that the thread is currently blocked on, if any, and which thread is holding that lock, as well as thread contention statistics.

• getThreadCpuTime: Returns the CPU time consumed by a given thread.

You can access these additional features through the MBeans tab by selecting Threading MXBean in the MBeans tree. This MXBean lists all the attributes and operations for accessing threading information in the Java VM being monitored. See Monitoring and Managing MBeans.

Detecting Deadlocked Threads

To check if your application has run into a deadlock (for example, your application seems to be hanging), deadlocked threads can be detected by clicking Detect Deadlock. If any deadlocked threads are detected, these are displayed in a new tab that appears next to the Threads tab, as shown in Figure 3-9.

Figure 3-9 Deadlocked Threads

Detect Deadlock will detect deadlock cycles involving object monitors and java.util.concurrent ownable synchronizers (see the API specification documentation for java.lang.management.LockInfo). Monitoring support for java.util.concurrent locks has been added in Java SE from version 6.0. If JConsole connects to a Java SE 5.0 VM, then the Detect Deadlock mechanism will find only deadlocks related to object monitors. JConsole will not show any deadlocks related to ownable synchronizers.

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

Monitoring Class Loading

The Classes tab displays information about class loading.

Figure 3-10 Classes Tab

The chart plots the number of classes loaded over time.

• The red line is the total number of classes loaded (including those subsequently unloaded).

• The 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 Java VM started, the number currently loaded, and the number unloaded. You can set the tracing of class loading to verbose output by selecting the check box in the top right-hand corner.

Viewing VM Information

The VM Summary tab provides information about the Java VM.

Figure 3-11 VM Summary Tab

The information presented in this tab includes the following:

• Summary

  • Uptime: Total amount of time since the Java VM was started.

  • Process CPU Time: Total amount of CPU time that the Java VM has consumed since it was started.

  • Total Compile Time: Total accumulated time spent in JIT compilation. The Java VM 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.

• Threads

  • Live threads: Current number of live daemon threads plus nondaemon threads.

  • Peak: Highest number of live threads since Java VM started.

  • Daemon threads: Current number of live daemon threads.

  • Total threads started: Total number of threads started since Java VM started, including daemon, nondaemon, and terminated threads.

• Classes

  • Current classes loaded: Number of classes currently loaded into memory.

  • Total classes loaded: Total number of classes loaded into memory since the Java VM started, including those that have subsequently been unloaded.

  • Total classes unloaded: Number of classes unloaded from memory since the Java VM started.

• Memory

  • Current heap size: Number of kilobytes currently occupied by the heap.

  • Committed memory: Total amount of memory allocated for use by the heap.

  • Maximum heap size: Maximum number of kilobytes occupied by the heap.

  • Objects pending for finalization: Number of objects pending for finalization.

  • Garbage collector: Information about garbage collection, including the garbage collector names, number of collections performed, and total time spent performing GC.

• Operating System

  • Total physical memory: Amount of random access memory (RAM) the operating system has.

  • Free physical memory: Amount of free RAM available to the operating system.

  • Committed virtual memory: Amount of virtual memory guaranteed to be available to the running process.

• Other Information

  • VM arguments: The input arguments that the application passed to the Java VM, not including the arguments to the main method.

  • Class path: The class path that is used by the system class loader to search for class files.

  • Library path: The list of paths to search when loading libraries.

  • Boot class path: The path used by the bootstrap class loader to search for class files.

Monitoring and Managing MBeans

The MBeans tab displays information about all the MBeans registered with the platform MBean server in a generic way. The MBeans tab allows you to access the full set of the platform MXBean instrumentation, including the ones that are not visible in the other tabs. In addition, you can monitor and manage your application's MBeans using the MBeans tab.

Figure 3-12 MBeans Tab

The tree on the left shows all the MBeans currently running. When you select an MBean in the tree, its MBeanInfo and its MBean Descriptor are both displayed on the right, and any attributes, operations, or notifications appear in the tree below it.

All the platform MXBeans and their various operations and attributes are accessible from JConsole's MBeans tab.

Constructing the MBean Tree

By default, the MBeans are displayed in the tree based on their object names. The order of key properties specified when the object names are created is preserved by JConsole when it adds MBeans to the MBean tree. The exact key property list that JConsole will use to build the MBean tree will be the one returned by the method ObjectName.getKeyPropertyListString(), with type as the first key, and j2eeType, if present, as the second key.

However, relying on the default order of the ObjectName key properties can sometimes lead to unexpected behavior when JConsole renders the MBean tree. For example, if two object names have similar keys but their key order differs, then the corresponding MBeans will not be created under the same node in the MBean tree.

For example, suppose you create Triangle MBean objects with the following names.

com.sun.example:type=Triangle,side=isosceles,name=1
com.sun.example:type=Triangle,name=2,side=isosceles
com.sun.example:type=Triangle,side=isosceles,name=3

As far as the JMX technology is concerned, these objects will be treated in exactly the same way. The order of the keys in the object name makes no difference to the JMX technology. However, if JConsole connects to these MBeans and the default MBean tree rendering is used, then the object com.sun.example:type=Triangle,name=2,side=isosceles will end up being created under the Triangle node, in a node called 2, which in turn will contain a subnode called isosceles. The other two isosceles triangles, name=1 and name=3, will be grouped together under Triangle in a different node called isosceles, as shown in Figure 3-13.

Figure 3-13 Example of Unexpected MBean Tree Rendering

To avoid this problem, you can specify the order in which the MBeans are displayed in the tree by supplying an ordered key property list when you start JConsole at the command line. This is achieved by setting the system property com.sun.tools.jconsole.mbeans.keyPropertyList, as shown in the following command.

% jconsole -J-Dcom.sun.tools.jconsole.mbeans.keyPropertyList=key[,key]*

The key property list system property takes a comma-separated list of keys, in the order of your selection, where key must be a string representing an object name key or an empty string. If a key specified in the list does not apply to a particular MBean, then that key will be discarded. If an MBean has more keys than the ones specified in the key property list, then the key order defined by the value returned by ObjectName.getKeyPropertyListString() will be used to complete the key order defined by keyPropertyList. Therefore, specifying an empty list of keys means that JConsole will display keys in the order that they appear in the MBean's ObjectName.

So, returning to the example of the Triangle MBeans cited previously, you can start JConsole by specifying the keyPropertyList system property, so that all your MBeans will be grouped according to their side key property first, and their name key property second. To do this, start the JConsole with the following command:

% jconsole -J-Dcom.sun.tools.jconsole.mbeans.keyPropertyList=side,name

Starting JConsole with this system property specified will produce the MBean tree as shown in the Figure 3-14.

Figure 3-14 Example of MBean Tree Constructed Using keyPropertyList

In Figure 3-14, the side key comes first, followed by the name key. The type key comes at the end because it was not specified in the key property list, so the MBean tree algorithm applied the original key order for the remaining keys. Consequently, the type key is appended at the end, after the keys, which were defined by the keyPropertyList system property.

According to the object name convention defined by the JMX Best Practices Guidelines, the type key should always come first. You must start JConsole with the following system property:

% jconsole -J-Dcom.sun.tools.jconsole.mbeans.keyPropertyList=type,side,name

The prior command will cause JConsole to render the MBean tree for the Triangle MBeans as shown in the Figure 3-15.

Figure 3-15 Example of MBean Tree Constructed Respecting JMX Best Practices

This is comprehensible than the MBean trees as shown in Figure 3-13 and Figure 3-14.

MBean Attributes

Selecting the Attributes node displays all the attributes of an MBean. Figure 3-16 shows all the attributes of the Threading platform MXBean.

Figure 3-16 Viewing All MBean Attributes

Selecting an individual MBean attribute from the tree then displays the attribute's value, its MBeanAttributeInfo, and the associated Descriptor in the right pane, as you can see in Figure 3-17.

Figure 3-17 Viewing an Individual MBean Attribute

You can display additional information about an attribute by double-clicking the attribute value, if it appears in bold text. For example, if you click the value of the HeapMemoryUsage attribute of the java.lang.Memory MBean, then you will see a chart that looks something like Figure 3-18.

Figure 3-18 Displaying Attribute Values

Double-clicking numeric attribute values will display a chart that plots changes in that numeric value. For example, double-clicking the CollectionTime attribute of the Garbage Collector MBean PS Marksweep will plot the time spent performing garbage collection.

You can also use JConsole to set the values of writable attributes. The value of a writable attribute is displayed in blue. Here you can see the Memory MBean's Verbose attribute.

Figure 3-19 Setting Writable Attribute Values

You can set attributes by clicking them and then editing them. For example, to enable or disable the verbose tracing of the garbage collector in JConsole, select the Memory MXBean in the MBeans tab and set the Verbose attribute to true or false. Similarly, the class loading MXBean also has the Verbose attribute, which can be set to enable or disable class loading verbose tracing.

MBean Operations

Selecting the Operations node displays all the operations of an MBean. The MBean operations appear as buttons, that you can click to call the operation. Figure 3-20 shows all the operations of the Threading platform MXBean.

Figure 3-20 Viewing All MBean Operations

Selecting an individual MBean operation in the tree displays the button for calling the MBean operation, and the operation's MBeanOperationInfo and its Descriptor, as shown in Figure 3-21.

Figure 3-21 Viewing Individual MBean Operations

MBean Notifications

You can subscribe to receive notifications by selecting the Notifications node in the left-hand tree, and clicking the Subscribe button that appears on the right. The number of notifications received is displayed in brackets, and the Notifications node itself will appear in bold text when new notifications are received. The notifications of the Memory platform MXBean are shown in Figure 3-22.

Figure 3-22 Viewing MBean Notifications

Selecting an individual MBean notification displays the MBeanNotificationInfo in the right pane, as shown in Figure 3-23.

Figure 3-23 Viewing Individual MBean Notifications

HotSpot Diagnostic MXBean

JConsole's MBeans tab also allows you to tell the HotSpot VM to perform a heap dump, and to get or set a VM option using the HotSpotDiagnostic MXBean.

Figure 3-24 Viewing the HotSpot Diagnostic MBean

You can perform a heap dump manually by calling the com.sun.management.HotSpotDiagnostic MXBean's dumpHeap operation. In addition, you can specify the HeapDumpOnOutOfMemoryError Java VM option using the setVMOption operation, so that the VM performs a heap dump automatically whenever it receives an OutOfMemoryError.

Creating Custom Tabs

In addition to the existing standard tabs, you can add your own custom tabs to JConsole, to perform your own monitoring activities. The JConsole plug-in API provides a mechanism by which you can, for example, add a tab to access your own application's MBeans. The JConsole plug-in API defines the com.sun.tools.jconsole.JConsolePlugin abstract class that you can extend to build your custom plug-in.

As stated previously, your plug-in must extend JConsolePlugin, and implement the JConsolePlugingetTabs and newSwingWorker methods. The getTabs method returns either the list of tabs to be added to JConsole, or an empty list. The newSwingWorker method returns the SwingWorker to be responsible for the plug-in's GUI update.

Your plug-in must be provided in a Java archive (JAR) file that contains a file named META-INF/services/com.sun.tools.jconsole.JConsolePlugin. This JConsolePlugin file itself contains a list of all the fully qualified class names of the plug-ins that you want to add as new JConsole tabs. JConsole uses the service-provider loading facility to look up and load the plug-ins. You can have multiple plug-ins, with one entry per plug-in in the JConsolePlugin.

To load the new custom plug-ins into JConsole, start JConsole with the following command:

%  jconsole -pluginpath plugin-path

In the previous command, plugin-path specifies the paths to the JConsole plug-ins to be looked up. These paths can either be to directory names or to JAR files, and multiple paths can be specified, using your platform's standard separator character.

An example JConsole plug-in is provided with the Java SE 13 platform. The JTop application is a JDK demonstration (demo) that shows the CPU usage of all threads running in the application. This demo is useful for identifying threads that have high CPU consumption, and it has been updated to be used as a JConsole plug-in as well as a standalone GUI. JTop is bundled with the Java SE 13 platform, as a demo application. You can run JConsole with the JTop plug-in by running the following command:

% JDK_HOME/bin/jconsole -pluginpath JDK_HOME/demo/management/JTop/JTop.jar

If you connect to this instance of JConsole, then you will see that the JTop tab has been added, showing CPU usage of the various threads running.

Figure 3-25 Viewing a Custom Plug-in Tab