visualgc - Visual Garbage Collection Monitoring Tool

SYNOPSIS

visualgc 
-help
        

Output a usage message and exit.

visualgc 
-version
        

Output version identification information exit.

visualgc 
vmid [
interval]
        

vmid

See vmid in the Options section below.

interval

See interval in the Options section below.

DESCRIPTION

The visualgc tool attaches to an instrumented HotSpot JVM and collects and graphically displays garbage collection, class loader, and HotSpot compiler performance data.

The target JVM is identified by its virtual machine identifier, or vmid. The formatting and semantics of the vmid are described in the vmid option section below.

OPTIONS

The visualgc takes the following options:

vmid

A string that indicates the target JVM. The syntax of the vmid string largely corresponds to the syntax of a URI. The general syntax is

[ protocol:][//] lvmid [@ hostname[: port]/ servername]

which allows virtual machine identifiers to vary from a simple integer representing a local virtual machine identifier to a more complex construction specifying a communications protocol, port number, and other implementation specific values. See the Virtual Machine Identifier section for more details.

interval[ms|s]

An integer value indicating the sampling interval. The default units is ms (milliseconds). If omitted, the default interval is 500 milliseconds.

OUTPUT FORMAT

The visualgc tool will open two or three windows: the Visual GC window, the Graph window, and optionally the Survivor Age Histogram window. The Survivor Age Histogram window not only available when the Parallel Scagenge collection (-XX:+UseParallelGC or -XX:+AggressiveHeap) is in use.

Visual GC Window

The VisualGC window is upper leftmost window and is comprised of two panels. The top panel, labeled Application Information contains a liveness indicator and the elapsed time since the start of the target Java application. It also contains a scrollable text area that lists miscellaneous information about the configuration of the target Java application and JVM. This section includes the target application's main class name (or jar file if the application was started with the -jar option), and the arguments to the class's main method. It also includes the arguments passed to the JVM and the values of certain Java properties exported as instrumentation objects.

The bottom panel provides a graphical view of the spaces that make up the generational garbage collection system. This panel is divided up unto three vertical sections, one for each of the of the generations: the Perm (or Permanent) generation, the Old (or Tenured) generation, and the Young generation. The Young generation section is comprised of three separate spaces that occupy the rightmost vertical slice of this panel. The three spaces are the Eden space and two Survivor spaces, S0 and S1.

The screen areas representing the various spaces are sized proportionately to the maximum capacities of the spaces. The screen areas for the three generations are of fixed size and do not vary over time. Each space is filled with a unique color indicating the current utilization of the space, relative to its maximum capacity. The unique color for each space is used consistently among this window and the Graph and Survivor Age Histogram windows.

The memory management system in the HotSpot JVM is capable of growing and shrinking the garbage collected heap. This is accomplished by reserving address space for the requested maximum heap size, but committing real memory to only the amount currently needed. The relationship between committed and reserved memory is represented by the color of the background grid in each space. Uncommitted memory is represented by the dark gray colored portion of the grid whereas committed memory is represented by the green colored portion of the grid. In many cases, the utilization of the space may be nearly identical to the committed amount of memory, making it difficult to determine the exact transition point of the green portion of the grid to the gray portion of the grid.

The relationship between the sizes of the Eden and Survivor spaces in the young generation portion of the Visual GC frame are usually fixed in size. The survivor spaces are of identical size and are fully committed, indicated by the grid that is all green. The Eden space may be only partially committed, with the uncommitted portion of the space represented by dark gray portion of the grid.

When the parallel young generation collector (-XX:+UseParallelGC) is used along with the adaptive size policy feature (-XX:+UseAdaptiveSizePolicy), the relationship between the sizes of the young generation spaces can vary over time. When this collector policy is in effect, the sizes of the of the survivor spaces are not necessarily identical and space in the young generation can be dynamically redistributed among the three spaces. In this configuration, the screen areas representing the Survivor spaces and the colored region representing the utilization of the space are sized relative to the current size of the space, not the maximum size of the space. When dynamic resizing occurs, the screen area associated with the young generation spaces will change accordingly.

Graph Window

The Graph window displays plots the values of various statistics as a function of time. The resolution of the horizontal axis of the graph is determined by the interval command line argument, where each sample occupies 2 pixels of screen area. The height of each display depends on the metric being plotted.

The following displays are provided

Compile Time

This panel plots the amount of time spent compiling Java byte codes into native code. The height of this display is not scaled to any particular value. A non zero value in this graph indicates that compilation activity occurred during the last interval. A narrow pulse indicates a relatively short duration and a wide pulse indicates a long duration. The title bar indicates the number of compilation tasks and the accumulated compilation time since the start of the application.

Class Loader Time

This panel plots the amount of time spent in class loading and unloading activities. The height of this display is not scaled to a particular value. A non zero value in this graph indicates that class loading activity occurred during the last interval. A narrow pulse indicates a relatively short duration and a wide pulse indicates a long duration. The title bar indicates the number of classes loaded and unloaded and the accumulated class loading time since the start of the application.

GC Time

This panel plots the amount of time spent in garbage collection activities. The height of this display is not scaled to any particular value. A non zero value in this graph indicates that garbage collection activity occurred during the last interval. A narrow pulse indicates a relatively short duration and a wide pulse indicates a long duration. The title bar indicates the total number of GC events and the accumulated GC time since the start of the application.

If the target JVM maintains the hotspot.gc.cause and hotspot.gc.last_cause counters, the cause of the GC events will also be displayed in the title bar for this graph.

Eden Space

This panel plots the utilization of the Eden Space over time. The Eden Space is one of three spaces that make up the Young Generation. The height of this panel is fixed and, by default, the data is scaled according to the current capacity of the space. Since the current capacity of the space can change dynamically depending on the collector policy, visual artifacts may occur as the space shrinks and grows over time.

The title bar displays the name of the space and its maximum and current capacity in parenthesis followed by the current utilization of the space. In addition, the title also contains the number and accumulated time of Young GC events.

Survivor 0 and Survivor 1

The Survivor panels plot the utilization of the two survivor spaces over time. The Survivor Spaces are the remaining two spaces comprising the Young Generation. The height of each of these panels is fixed and, by default, the data is scaled according to the current capacity of the corresponding space. Since the current capacity of the survivor spaces can change dynamically depending on the collector policy, visual artifacts may occur as the space shrinks and grows over time.

The title bar displays the name of the space and its maximum and current capacity in parenthesis followed by the current utilization of the space.

Old Gen

The Old Gen panel plots the utilization of the Old Generation over time. The Old Generation is comprised of a single space. The height of the panel is fixed and, by default, the data is scaled according to the current capacity of the space. Since the current capacity of the space can change dynamically depending on the collector policy, visual artifacts may occur as the space shrinks and grows over time.

The title bar displays the name of the space and its maximum and current capacity in parenthesis followed by the current utilization of the space. In addition, the title also contains the number and accumulated time of Full GC events.

Perm Gen

The Perm Gen panel plots the utilization of the Permanent Generation over time. The Permanent Generation is comprised of a single space, but does not have its own collector. Instead, this space is collected as part of the Old Generation. The height of the panel is fixed and, by default, the data is scaled according to the current capacity of the space. Since the current capacity of the space can change dynamically depending on the collector policy, visual artifacts may occur as the space shrinks and grows over time.

The title bar displays the name of the space and its maximum and current capacity in parenthesis followed by the current utilization of the space.

Each of the GC space graphs can be displayed in one of two modes - reserved mode or committed mode, with committed mode being the default. In reserved mode, the data is scaled according to the maximum capacity of the space while in committed mode, the data is scaled according to the current capacity of the space. In reserved mode, the background grid is painted in dark gray to represent that portion of the reserved memory that is uncommitted memory and in green to represent the portion that is committed. The mode can be toggled by right-clicking over the space and checking or un-checking the "Show Reserved Space" check box.

Survivor Age Histogram Window

The Survivor Age Histogram window is the lowermost window. It is comprise of two panels, the Parameters panel and the Histogram panel.

The Parameters panel displays the size of the survivor spaces and the parameters that control the promotion behavior of the young generation. After each young generation collection, objects that survive the collection but are not promoted remain in the Survivor spaces. An object's age is incremented each time it survives a young generation collection until the object's age reaches the maximum age as defined by the TenuringThreshold variable, which varies between 1 and MaxTenuringThreshold-1 depending on the utilization of the survivor space. If the survivor space overflows, then the oldest objects are promoted to the Old generation until the utilization of the space does not exceed DesiredSurvivorSize. A MaxTenuringThreshold value of 0 will result in objects always being promoted to the old generation and a value 32 will prevent objects from being promoted unless the survivor space fills up.

The Histogram panel displays a snapshot of the age distribution of objects in the active survivor space after the last Young generation collection. The display is comprised of 32 identically sized regions, one for each possible object age. Each region represents 100% of the active Survivor Space and is filled with a colored area that indicates the percentage of the survivor space occupied by objects of the given age.

When the target JVM is started with the parallel young generation collector (-XX:+UseParallelGC), the Survivor Age Histrogram window is not displayed. The parallel young generation collector does not maintain a survivor age histogram as it applies a different policy for maintaining objects in the survivor spaces.

Window Sizing and Placement and Color Selection

The visualgc tool provides some crude window sizing and placement and color selection capabilities through the setting over various Java system properties. These properties can be passed to the visualgc script through the VMARGS environment variable. The following table lists the available properties:

To change the value of a color, an RGB value must be specified in either decimal, octal, or hexadecimal. A color name, such as Color.CYAN, or a Color constructor call, such as Color(255, 150, 0), as used in the defaults column of the above table, are not accepted as valid values for the above properties.

EXAMPLES

To monitor a local HotSpot JVM, its local virtual machine identifier , or lvmid must first be determined. The jps command should be used to determine the local virtual machine identifier for the target JVM. Although a lvmid is simply a process identifier on UNIX platforms and Windows platforms, acquiring a process identifier from platform specific tools such as ps or Task Manager may not be sufficient. In general, if the jps does not list the target application in its output, then the target is not monitorable by the user running the tools. Furthermore, operating systems other than UNIX and Windows may not have such a direct mapping from an operating system abstraction to an lvmid, in which case the operating system specific tools may not be able to provide a corresponding identifier.

Once the lvmid has been determined, it can be used directly for local monitoring or as a component of a more general Virtual Machine Identifier, or vmid, for the visualgc command.

Visualizing operations of a local JVM

This example uses jps to get a list of available target JVMs and then uses visualgc to attach to the JVM for the Java2Demo application with lvmid 21891. The sampling interval is set to 250 milliseconds.

 %

           jps
21891 Java2Demo.jar
1362 Jps.jar
%  
 visualgc 21891 250
              

Visualizing operations of a remote JVM

This uses jps to get a liast of availale target JVMs on the host named remote.domain and then uses visualgc to attach to the JVM for the Java2Demo application with lvmid 102592 on the remote system. The sample interval is not specified in this example and the default interval of 500 milliseconds is used.

 %

 jps remote.domain
81763 Jps
1362 Jstatd
102592 Java2Demo.jar
%  
visualgc 102592@remote.domain
              

The vmid in this example implies that the remote protocol is RMI. This implication requires that an RMI registry bound to the default port (1099) and the jstatd server are running on remote.domain. In addition, it also assumes that the jstatd server is running with appropriate credentials to access the JVM itendified by lvmid 102592.

BUGS

The visualgc tool was originally developed as demonstration software for JavaOne 2001 where it was used in a presentation to help describe how various tunable parameters affect the operations of the HotSpot generational garbage collector. This application was modified to use the jvmstat APIs to acquire data from a live instrumented JVM.

The future of this tool is unknown and bugs may or may not be fixed in future releases. The tool may be replaced by a more generic, but configurable tool that can provide similar information.

SEE ALSO

• java - the Java Application Launcher
• jps - the Java Process Status Application
• jstat - the Java Virtual Machine Statistics Monitoring Tool
• jstatd - the jstat monitoring daemon
• rmiregistry - the Java Remote Object Registry