jvmstat - Java Virtual Machine Statistics Monitoring Tool

SYNOPSIS

jvmstat -help 
Output a usage message and exit.
jvmstat -version 
Output version information and exit.
jvmstat -options 
Output a list of special formatting options and exits. See the -option usage and Formatted Output sections below.
jvmstat -option [-t] [-hlines] vmid [interval [count]]
-option
The list of options reported by the -options argument indicates the special formatting options accepted as first argument to the jvmstat command. These options invoke customized formatting functions of the jvmstat command. See Formatted Output below.
-t
See -t in the Options section below.
-h lines
See -h in the Options section below.
vmid
See vmid in the Options section below.
interval
See interval in the Options section below.
count
See count in the Options section below.
jvmstat -list [vmid]
Output a list of currently available instrumentation objects for the Java Virtual Machine indicated by vmid. If vmid is omitted, 0 is assumed. The currently available instrumentation objects can vary depending on the configuration or current state of the target Java Virtual Machine. See the instrumentation documentation. for a list of all possible instrumentation objects for a specific version of a HotSpot Java Virtual Machine.
jvmstat [[-a|-d] [-[no]constants] [-[no]strings] [-names name,[name]]] [-hlines] vmid [interval [count]]
-a | -d
See Sorting Options in the Options section below.
-[no]constants
See Filtering Options in the Options section below.
-[no]strings
See Filtering Options in the Options section below.
-names name[,name]
See Filtering Options in the Options section below.
-h lines
See -h in the Options section below.
vmid
See vmid in the Options section below.
interval
See interval in the Options section below.
count
See count in the Options section below.

DESCRIPTION

The jvmstat tool attaches to an instrumented HotSpot Java Virtual Machine and collects and logs performance statistics as specified by the command line options.

The target Java Virtual Machine is identified by its Virtual Machine Identifier, or vmid. The formatting and semantics of the vmid are described in the vmid option description below.

The jvmstat command can be run in various modes, as documented in the Synopsis section. The default mode, generates output in a raw format intended for consumption by filter processes. The formatted output modes, provide more concise, human readable output formats. The other modes provide information on usage and names of instrumentation objects. All output formats generated by the jvmstat command are uncommitted formats and are subject to change or removal in future releases.

OPTIONS

The jvmstat command supports a number of command line options. Some options have general applicability, others only apply when dependent options are used. See the Synopsis for usage patterns. These options, and their influence on the format of output, are uncommitted and are subject to change or removal in future releases.

vmid
A string that indicates the target Java Virtual Machine. 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 VM 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 10000 milliseconds, or 10 seconds.

count
An integer value indicating the number of samples. The default value for count is infinity. That is, by default jvmstat samples and logs statistics indefinitely, or until terminated by some alternative mechanism.

-h n
Output a column header every n samples. The default behavior, which is equivalent to n=0, is to output the column header once, prior to outputting the first row of data. Setting this value to a positive integer n will result in a column header line being printed followed by n rows of data.

-t n
Output a time stamp column as the first column of output. The time stamp value is the the time relative to the start time of the Java Virtual Machine indicated by the vmid argument.

-a | -d
Sort the columns of statistics in ascending or descending order by instrumentation object name. By default, the columns are sorted in ascending order.

-[no]constants
Control the output of instrumentation objects of type constant. This option defaults to -constants, which results in the output of a name=value pair for each instrumentation object that represents a constant value that is output before the header (if any) and before any samples.

-[no]strings
Control the output of non-constant instrumentation objects of type string. This option defaults to -nostrings and assures that the columnar data consists solely of 64 bit integer quantities. When the -strings option is set, columns representing variable length string data are output and these strings may contain arbitrary white space characters that interfere with the parseability of the output format.

-names name,[name]
Specify the instrumentation objects of interest. In terms of a Java regular expression, the default output of the jvmstat command is equivalent to specifying the -names "\S*" option. Since a typical instrumented Java Virtual Machine exports many instrumentation objects, the default output can be quite verbose. By naming specific instrumentation objects, or sets of instrumentation objects with regular expressions, the output can be limited to a select subset of the instrumentation. The regular expressions for the -names option must comply with the regular expression conventions specified by the Pattern class introduced in J2SE 1.4.0.

OUTPUT FORMAT

The output of the jvmstat command is dependent upon the options specified. In general, there are 2 types of output formats produced by jvmstat command: raw output intended for use by filters and post processing applications and formatted output intended for use by humans.

Raw Output Format

The raw output format is broken up into 3 sections of output.
Constants Section
If the -noconstants option is not specified on the command line and if the -names option includes instrumentation objects with a type characteristic of Constant, then the specified constant instrumentation objects are output once on startup as a sequence of name=value pairs.

Column Header Section
If the -h 0 option is not specified on the command, then a column header is output according as indicated by the -h option. A column header is a space separated list of instrumentation object names.

Data Rows Section
The final section of data is the data rows themselves. The data rows are comprised of space separated 64 bit signed integer values (Java long types). The order of the columns depends on the sort order specified by the -a or -d options.

Numeric data values are currently output in raw format. Time values are output in Ticks, which can be converted to units of time by scaling the ticks value by the hotspot.rt.hrt.frequency value. String values are also output in raw format and can introduce ambiguity into the columnar nature of the data when the strings contain internal white space. Future versions of this command will provide options for scaling the data and including units of measure.

The raw output format of the jvmstat command is variable and depends on the available instrumentation in the target Java Virtual Machine. For example, the column order and count may vary with the same command line options when monitoring Java Virtual Machines of different vintages or of the same vintage when started with different options. Scripts written to parse the output of the jvmstat command should be written such that column positions are not assumed.

If a specific column format is needed for reliable parsing purposes, the -names option should be used with each instrumentation object specified explicitly, without using any regular expression. In addition, the ascending or descending sorting option should also be specified. Under these conditions, the output format can be relied upon, assuming all the named instrumentation objects exist.

A future version of the raw output format may report when the available set of instrumentation has changed. When these state change conditions occur, a State Changed message will be output, potentially followed by the list of constants and the column header as controlled by the various command line options. The list of constants, the column header, and the number and positions of data fields may change whenever this event is detected.

Formatted Output

The value of the first option to the jvmstat command determines the output mode. The formatted output mode is used if the value of the first option to the jvmstat command is one of the special formatting options as listed by the -options option. The following formatted output mode options are available:
-class
Provides statistics on the behavior of the class loader.
Loaded
Number of classes loaded
Bytes
Number of bytes loaded, in Kilobytes.
Unloaded
Number of classes unloaded.
Bytes
Number of bytes unloaded, in Kilobytes.
Time
Time spent performing class load and unload operations.

-compiler
Provides statistics on the behavior of the HotSpot Just-in-Time compiler.
Compiled
Number of compilation tasks performed.
Failed
Number of compilation tasks that failed.
Invalid
Number of compilation tasks that were invalidated.
Time
Time spent performing compilation tasks.
FailedType
Compile type of the last failed compilation.
FailedMethod
Class name and method for the last failed compilation.

-gc
Provides statistics on the behavior of the garbage collected heap.
S0C
Survivor Space 0 Capacity - Current, in Kilobytes.
S1C
Survivor Space 1 Capacity - Current, in Kilobytes.
S0U
Survivor Space 0 Utilization, in Kilobytes.
S1U
Survivor Space 1 Utilization, in Kilobytes.
EC
Eden Space Capacity - Current, in Kilobytes.
EU
Eden Space Utilization, in Kilobytes.
OC
Old Space Capacity - Current, in Kilobytes.
OU
Old Space Utilization, in Kilobytes.
PC
Permanent Space Capacity - Current, in Kilobytes.
PU
Permanent Space Utilization, in Kilobytes.
YGC
Number of Young Generation GC Events.
YGCT
Young Generation Garbage Collection Time.
FGC
Number of Full GC Events.
FGCT
Full Garbage Collection Time.
GCT
Total Garbage Collection Time.

-gccapacity
Provides statistics on the capacities of the generations and their corresponding spaces.
NGCMN
New Generation Capacity - Minimum, in Kilobytes.
NGCMX
New Generation Capacity - Maximum, in Kilobytes.
NGC
New Generation Capacity - Current, in Kilobytes.
S0C
Survivor Space 0 Capacity - Current, in Kilobytes.
S1C
Survivor Space 1 Capacity - Current, in Kilobytes.
EC
Eden Space Capacity - Current, in Kilobytes.
OGCMN
Old Generation Capacity - Minimum, in Kilobytes.
OGCMX
Old Generation Capacity - Maximum, in Kilobytes.
OGC
Old Generation Capacity - Current, in Kilobytes.
OC
Old Space Capacity - Current, in Kilobytes.
PGCMN
Permanent Generation Capacity - Minimum, in Kilobytes.
PGCMX
Permanent Generation Capacity - Maximum, in Kilobytes.
PGC
Permanent Generation Capacity - Current, in Kilobytes.
PC
Permanent Space Capacity - Current, in Kilobytes.
YGC
Number of Young Generation GC Events.
FGC
Number of Full GC Events.

-gccause
Provides the same concise summary of garbage collection statistics as the -gcutil option, but includes the cause of the last and current (if applicable) garbage collection events.
S0
Survivor Space 0 utilization as a percentage of the space's current capacity.
S1
Survivor Space 1 utilization as a percentage of the space's current capacity.
E
Eden Space utilization as a percentage of the space's current capacity.
O
Old Space utilization as a percentage of the space's current capacity.
P
Permanent Space Utilization as a percentage of the space's current capacity.
YGC
Number of Young Generation GC Events.
YGCT
Young Generation Garbage Collection Time.
FGC
Number of Full GC Events.
FGCT
Full Garbage Collection Time.
GCT
Total Garbage Collection Time.
LGCC
Last Garbage Collection Cause.
GCC
Current Garbage Collection Cause

-gcnew
Provides statistics on the behavior of the New generation.
S0C
Survivor Space 0 Capacity - Current, in Kilobytes.
S1C
Survivor Space 1 Capacity - Current, in Kilobytes.
S0U
Survivor Space 0 Utilization, in Kilobytes.
S1U
Survivor Space 1 Utilization, in Kilobytes.
TT
Tenuring Threshold.
MTT
Maximum Tenuring Threshold.
DSS
Desired Survivor Size, in Kilobytes.
EC
Eden Space Capacity - Current, in Kilobytes.
EU
Eden Space Utilization, in Kilobytes.
YGC
Number of Young Generation GC Events.
YGCT
Young Generation Garbage Collection Time.

-gcnewcapacity
Provides statistics on the sizes of the New generations and its corresponding spaces.
NGCMN
New Generation Capacity - Minimum, in Kilobytes.
NGCMX
New Generation Capacity - Maximum, in Kilobytes.
NGC
New Generation Capacity - Current, in Kilobytes.
S0CMX
Survivor Space 0 Capacity - Maximum, in Kilobytes.
S0C
Survivor Space 0 Capacity - Current, in Kilobytes.
S1CMX
Survivor Space 1 Capacity - Maximum, in Kilobytes.
S1C
Survivor Space 1 Capacity - Current, in Kilobytes.
ECMX
Eden Space Capacity - Maximum, in Kilobytes.
EC
Eden Space Capacity - Current, in Kilobytes.
YGC
Number of Young Generation GC Events.
FGC
Number of Full GC Events.

-gcold
Provides statistics on the behavior of the Old and Permanent generations.
PC
Permanent Space Capacity - Current, in Kilobytes.
PU
Permanent Space Utilization, in Kilobytes.
OC
Old Space Capacity - Current, in Kilobytes.
OU
Old Space Utilization, in Kilobytes.
YGC
Number of Young Generation GC Events.
FGC
Number of Full GC Events.
FGCT
Full Garbage Collection Time.
GCT
Total Garbage Collection Time.

-gcoldcapacity
Provides statistics on the sizes of the Old generation.
OGCMN
Old Generation Capacity - Minimum, in Kilobytes.
OGCMX
Old Generation Capacity - Maximum, in Kilobytes.
OGC
Old Generation Capacity - Current, in Kilobytes.
OC
Old Space Capacity - Current, in Kilobytes.
YGC
Number of Young Generation GC Events.
FGC
Number of Full GC Events.
FGCT
Full Garbage Collection Time.
GCT
Total Garbage Collection Time.

-gcpermcapacity
Provides statistics on the sizes of the Permanent generation.
PGCMN
Perm Generation Capacity - Minimum, in Kilobytes.
PGCMX
Perm Generation Capacity - Maximum, in Kilobytes.
PGC
Perm Generation Capacity - Current, in Kilobytes.
PC
Perm Space Capacity - Current, in Kilobytes.
YGC
Number of Young Generation GC Events.
FGC
Number of Full GC Events.
FGCT
Full Garbage Collection Time.
GCT
Total Garbage Collection Time.

-gcutil
Provides a concise summary of garbage collection statistics.
S0
Survivor Space 0 utilization as a percentage of the space's current capacity.
S1
Survivor Space 1 utilization as a percentage of the space's current capacity.
E
Eden Space utilization as a percentage of the space's current capacity.
O
Old Space utilization as a percentage of the space's current capacity.
P
Permanent Space Utilization as a percentage of the space's current capacity.
YGC
Number of Young Generation GC Events.
YGCT
Young Generation Garbage Collection Time.
FGC
Number of Full GC Events.
FGCT
Full Garbage Collection Time.
GCT
Total Garbage Collection Time.

The column header names are generally consistent between the different output formats. In general, if two output formats are providing a column with the same name, then the data source for the two columns are the same.

Writing scripts to parse the output formats of the jvmstat command is not recommended as these output formats are not committed and may change in future releases. If you choose to write scripts that parse the output of the jvmstat command, expect to modify such scripts to work with new or changed output formats in future releases of this tool.

EXAMPLES

To monitor a local HotSpot Java Virtual Machine, its local VM identifier, or lvmid must first be determined. The jvmps command can be used to determine the local VM identifier for the target Java Virtual Machine. Since a lvmid is simply a process identifier on UNIX platforms, the UNIX platform specific ps command can also be used to determine the lvmid for the target Java Virtual Machine. Similarly, the Windows Task Manager can be used on Windows. Other operating systems may not have such a direct mapping from an operating system abstraction to the Java Virtual Machine lvmid. 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 jvmstat command.

Here are some examples of monitoring a local Java Virtual Machine with a lvmid of 21891.

Listing the available instrumentation objects

This example attaches to lvmid 21891 and lists all the available instrumentation objects exported by the target Java Virtual Machine.

% jvmstat -list 21891
hotspot.ci.CompilerThread0.compiles
hotspot.ci.CompilerThread0.method
hotspot.ci.CompilerThread0.time
hotspot.ci.CompilerThread0.type
hotspot.ci.failed.method
hotspot.ci.failed.type
...

Using a formatted output option

This example attaches to lvmid 21891 and takes 7 samples at 250 millisecond intervals and displays the output as specified by the formatted output option -gcutil.

% jvmstat -gcutil 21891 250 7
  S0     S1     E      O      P     YGC    YGCT    FGC    FGCT     GCT
 12.44   0.00  27.20   9.49  96.70    78    0.176     5    0.495    0.672
 12.44   0.00  62.16   9.49  96.70    78    0.176     5    0.495    0.672
 12.44   0.00  83.97   9.49  96.70    78    0.176     5    0.495    0.672
  0.00   7.74   0.00   9.51  96.70    79    0.177     5    0.495    0.673
  0.00   7.74  23.37   9.51  96.70    79    0.177     5    0.495    0.673
  0.00   7.74  43.82   9.51  96.70    79    0.177     5    0.495    0.673
  0.00   7.74  58.11   9.51  96.71    79    0.177     5    0.495    0.673

The output of this example shows that a young generation collection occurred between the 3rd and 4th sample. The collection took 0.001 seconds and promoted objects from the Eden space (E) to the Old space (O), resulting in an increase of Old space utilization from 9.49% to 9.51%. Before the collection, the survivor space was 12.44% utilized, but after this collection it is only 7.74% utilized.

Repeating the column header string

This example attaches to lvmid 21891 and takes samples at 250 millisecond intervals and displays the output as specified by the formatted output option -gcutil. In addition, it uses the -h3 option to output the column header after every 3 lines of data.

% jvmstat -gcnew -h3 21891 250
 S0C    S1C    S0U    S1U   TT MTT  DSS      EC       EU     YGC     YGCT
  64.0   64.0    0.0   31.7 31  31   32.0    512.0    178.6    249    0.203
  64.0   64.0    0.0   31.7 31  31   32.0    512.0    355.5    249    0.203
  64.0   64.0   35.4    0.0  2  31   32.0    512.0     21.9    250    0.204
 S0C    S1C    S0U    S1U   TT MTT  DSS      EC       EU     YGC     YGCT
  64.0   64.0   35.4    0.0  2  31   32.0    512.0    245.9    250    0.204
  64.0   64.0   35.4    0.0  2  31   32.0    512.0    421.1    250    0.204
  64.0   64.0    0.0   19.0 31  31   32.0    512.0     84.4    251    0.204
 S0C    S1C    S0U    S1U   TT MTT  DSS      EC       EU     YGC     YGCT
  64.0   64.0    0.0   19.0 31  31   32.0    512.0    306.7    251    0.204

In addition to showing the repeating header string, this example shows that between the 2nd and 3rd samples, a young gc occurred. Its duration was 0.001 seconds. The collection found enough live data that the Survivor Space 0 utilization (S0U) would would have exceeded the Desired Survivor Size (DSS). As a result, objects were promoted to the old generation (not visible in this output), and the Tenuring Threshold (TT) was lowered from 31 to 2.

Another collection occurs between the 5th and 6th samples. This collection found very few survivors and returned the Tenuring Threshold to 31.

Including a time stamp for each sample

This example attaches to lvmid 21891 and takes 3 samples at 250 millisecond intervals. The -t option is used to generate a time stamp for each sample in the first column.

% jvmstat -gcoldcapacity -t 21891 250 3
Timestamp          OGCMN        OGCMX         OGC           OC       YGC   FGC    FGCT    GCT
          150.1       1408.0      60544.0      11696.0      11696.0   194    80    2.874   3.799
          150.4       1408.0      60544.0      13820.0      13820.0   194    81    2.938   3.863
          150.7       1408.0      60544.0      13820.0      13820.0   194    81    2.938   3.863

The Timestamp column reports the elapsed time in seconds since the start of the Java Virtual Machine. In addition, this example also shows the Old Generation Capacity (OGC) and the Old Space Capacity (OC) increasing as the heap expands to meet allocation and/or promotion demands. The Old Generation Capacity (OGC) has grown to from 11696 KB to 13820 KB after the 81st Full GC (FGC). The maximum capacity of the generation (and space) is 60544 KB (OGCMX), so it still has room to expand.

Monitor all instrumentation

This example shows a simplistic use of the jvmstat command. This example attaches to lvmid 21891 and samples at 1 second intervals for an indefinite period of time.

% jvmstat 21891 1000
... output omitted

Monitor all instrumentation for a remote Java Virtual Machine

This example attaches to lvmid 40496 on the system named remote.domain and monitors all its available instrumentation at 1 second intervals for an indefinite number of samples.

% jvmstat 40496@remote.domain 1000
... output omitted

The lvmid is combined with the name of the remote host to construct a vmid of 40496@remote.domain. This vmid results in the use of the rmi protocol to communicate to the default perfagent server on the remote hosts. The perfagent is located using the rmiregistry on remote.domain that is bound to the default rmiregistry port (port 1099).

Monitor specific instrumentation objects

This example attaches to lvmid 21891 and takes 7 samples of two specific counters, sampling at 1 second intervals. The output is in raw format.

% jvmstat -names "hotspot.ci.total.compiles|hotspot.ci.total.time" 21891 1000 7
hotspot.ci.total.compiles hotspot.ci.total.time 
78 5316274102 
80 5334044448 
83 5408104308 
84 5437117324 
86 5823263363 
86 5823263363 
87 5829436844 

Monitor specific instrumentation objects using a pattern

This example attaches to lvmid 21891 and takes 7 samples of the instrumentation objects that match a specific pattern. The pattern in this example will select all Eden space metrics and sample them at 1 second intervals.

% jvmstat -names "hotspot.gc.generation.0.space.0.\S*" 21891 1s 7
hotspot.gc.generation.0.space.0.name=eden
hotspot.gc.generation.0.space.0.size=4194304
 
hotspot.gc.generation.0.space.0.capacity hotspot.gc.generation.0.space.0.used
524288 502424
524288 219504
524288 459872
524288 176112
524288 416544
524288 132808
524288 327280

The output for this example also shows how the jvmstat command will list constant values once before outputting the periodically sampled metrics.

Printing raw string values and a raw time stamps

This example attaches to lvmid 21891 and takes 10 samples of specific instrumentation objects at 10ms intervals. It uses the -strings argument to force the inclusion of instrumentation objects containing string data, which are normally omitted. It also includes the value of the hotspot.rt.hrt.ticks counter, which contains the elapsed time (in ticks) since the start of the target Java Virtual Machine.

% jvmstat -strings -names "hotspot.rt.hrt.ticks","hotspot.ci.CompilerThread\S*" 21891 10 9
hotspot.ci.CompilerThread0.compiles hotspot.ci.CompilerThread0.method hotspot.ci.CompilerThread0.time hotspot.ci.CompilerThread0.type hotspot.rt.hrt.ticks
650 "" 821 1 71617183
650 "" 821 1 71677489
651 "" 822 1 71677489
651 "" 822 1 71677489
653 "" 825 1 71797280
653 "" 825 1 71797280
654 "sun/awt/motif/MComponentPeer getGraphics" 826 1 71864061
654 "" 826 1 71864061
654 "" 826 1 71864061

The output for this example shows the number of compile tasks serviced by Compiler Thread 0 (hotspot.ci.CompilerThread0.compiles), the name of the method the thread is currently compiling (hotspot.ci.CompilerThread0.method). the elapsed time (in ticks) that Compiler Thead 0 has consumed compiling methods (hotspot.ci.CompilerThread0.time), and the type of the current compile task (hotspot.ci.CompilerThread0.type).

Note that the name of the current method being compiled will almost always be null as the compiler will null out this value when not compiling a method. In general, compilation occurs too quickly for jvmstat to catch a value in this counter unless sampling at relatively high frequencies.

SEE ALSO


Copyright © 2003 Sun Microsystems, Inc. All Rights Reserved.

Sun
Java Software