Using jconsole

Jconsole is a JMX-compliant monitoring tool.  It uses theextensive JMX instrumentation of the Java virtual machine toprovide information on performance and resource consumption ofapplications 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 inJDK_HOME/bin, whereJDK_HOME is the directory where the JDK isinstalled.  If this directory is on your system path, you canstart the tool by simply typing jconsole in a command(shell) prompt. Otherwise, you have to type the full path to theexecutable file.

Command Syntax

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

Note: Using jconsole to monitor a local application is useful for developmentand prototyping, but is not recommended for production environments,because jconsole itself consumes significant systemresources. Remote monitoring is recommended to isolate thejconsole application from the platform beingmonitored.

For a complete reference on jconsole command syntax, see jconsole - Java Monitoring andManagement 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 tofind the PID of java.
• On Windows systems, use Task Manager to find the PID ofjava or javaw.

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

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

jconsole 2956

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

If  you don't specify a process ID, jconsole will automatically detectall local Java applications, and display a dialog box that lets you select the one you want tomonitor (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 theapplication and portNum is the port number you specifiedwhen 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 numbercombination, 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, itwill automatically start monitoring the specified JVM. You can connect to a different host at any time by choosingConnection | New Connection. and entering the necessaryinformation.

Otherwise,if you do not provide any arguments when you start jconsole, the first thing you see is theconnection 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 withtheir process ID and class/argument information.  Select theapplication 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 isrunning.
• Port number: the JMX agent port number you specified when youstarted the JVM.
• User name and password: the user name and password to use (requiredonly if monitoring a  JVM through a JMX agent that requirespassword authentication).

For information on setting the port number of the JMX agent, seeEnabling the JMX ManagementAgent. For information on user names and passwords, seeUsing Password and AccessFiles.

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

Advanced Tab

The advanced tab enables you to connect to other JMX agents (MBeanservers) by specifying their JMX URL, and the user name andpassword.  The syntax of a JMX URL is described in the APIdocumentation 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 jconsoleinterface

The jconsole interface is composed of six tabs:

• Summary tab: displays summary information on the JVM andmonitored 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 threadusage, memory consumption, and class loading, plus information onthe JVM and operating system.

Summary

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

Threads

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

Memory

• Current heap size: Number of Kbytes currently occupiedby the heap.
• Committed memory: Total amount of memory allocated foruse by the heap.
• Maximum heap size: Maximum number of Kbytes occupied bythe 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 currentlyloaded into memory.
• Total classes loaded: Total number of classes loadedinto memory since the JVM started, included those subsequently unloaded.
• Total classes unloaded: Number of classes unloaded frommemory 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 OShas.
• Committed virtual memory: Amount of virtual memory guaranteed to be available to the running process.

Monitoring MemoryConsumption

The Memory tab provides information on memory consumption andmemory pools.

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

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

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

The Details area shows several current memorymetrics:

• Used: the amount of memory currently used. Memoryused includes the memory occupied by all objects including bothreachable and unreachable objects.
• Committed: the amount of memory guaranteed to beavailable for use by the JVM. The amount of committed memory maychange over time. The Java virtual machine may release memory tothe system and committed could be less than the amount of memory initially allocated at startup. Committed willalways be greater than or equal to used.
• Max: the maximum amount of memory that can be used formemory management. Its value may change or be undefined. A memoryallocation may fail if the JVM attempts to increase the used memoryto be greater than committed memory, even if the amount used isless than or equal to max (for example, when the system is low onvirtual memory).

The bar chart at the lower right shows memory consumed by thememory pools in heap and non-heap memory.  The bar will turn redwhen the memory used exceeds the memory usage threshold.  You canset 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 JVMallocates memory for all class instances and arrays. The heap maybe of a fixed or variable size. The garbage collector is anautomatic memory management system that reclaims heap memory forobjects.

Non-heap memory includes a method area shared among allthreads and memory required for the internal processing oroptimization for the JVM. It stores per-class structures such as aruntime constant pool, field and method data, and the code formethods and constructors. The method area is logically part of theheap but, depending on implementation, a JVM may not garbagecollect or compact it. Like the heap, the method area may be offixed or variable size. The memory for the method area does notneed to be contiguous.

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

Memory Pools and Memory Managers

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

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

A memory manager manages one or more memory pools. Thegarbage collector is a type of memory manager responsible forreclaiming memory used by unreachable objects. A JVM may have oneor more memory managers. It may add or remove memory managersduring execution. A memory pool can be managed by more than onememory manager.

Garbage Collection

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

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

• many objects that have short lives (for example, iterators andlocal variables).
• some objects that have very long lifetimes (for example, highlevel persistent objects)

So, generational GC divides memory into severalgenerations, and assigns each a memory pool. When ageneration uses up its allotted memory, the VM performs a partialgarbage collection (also called a minor collection) on thatmemory pool to reclaim memory used by dead objects. This partial GCis usually much faster than a full GC.

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

The default arrangement of generations looks something likethis:

As explained in the following documents, if the garbagecollector has become a bottleneck, you can improve performance bycustomizing the generation sizes. Using jconsole, explore thesensitivity of your performance metric to the garbage collectorparameters. For more information, see:

• TuningGarbage 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 willshow only those threads whose name contains the string you enter. Click on the name of a thread in the Threads list to displayinformation about that thread to the right, including the threadname, state, and stack trace.

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

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

See java.lang.Thread for moreinformation about threads and daemon threads.

Monitoring ClassLoading

The Classes tab displays information on class loading.

The graph plots the number of classes loaded versustime:

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

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

Monitoring and ManagingMBeans

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

The tree on the left shows all the MBeans, organizedaccording to their objectNames. When you select an MBean in thetree, its attributes, operations, notifications and otherinformation is displayed on the right.

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

Displaying a Chart

You can display a chart of an attribute's value versus time bydouble-clicking on the attribute value.  For example, if you clickon the value of the CollectionTime property ofjava.lang.GarbageCollector.Copy MBean, you will see a chart that lookssomething like this:

Viewing VM Information

The VM tab provides information on the JVM.

The information includes:

• Uptime: Total amount of time since the JVM wasstarted.
• Process CPU Time: Total amount of CPU time that the JVMhas consumed since it was started.
• Total Compile Time: Total accumulated time spent injust-in-time (JIT) compilation. The JVM implementation determineswhen JIT compilation occurs. The Hotspot VM uses adaptivecompilation, in which the VM launches an application using astandard interpreter, but then analyzes the code as it runs todetect performance bottlenecks, or "hot spots".