jvmsnap - Java Virtual Machine Instrumentation Snapshot Tool

SYNOPSIS

jvmsnap -help 
Output a usage message and exit.
jvmsnap -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.
jvmsnap [[-a|-d] [-v] [-sC] [-names name,[name]]] vmid 
-a | -d
See Sorting Options in the Options section below.
-sC
See Format Options in the Options section below.
-v
See Format Options in the Options section below.
-names name[,name]
See Filtering Options in the Options section below.
vmid
See vmid in the Options section below.

DESCRIPTION

The jvmsnap tool attaches to an instrumented HotSpot Java Virtual Machine and takes a snapshot of the indicated instrumentation objects as specified by the command line options. Output is formated as rows of name=value pairs.

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.

All output formats generated by the jvmsnap command are uncommitted formats and are subject to change or removal in future releases.

OPTIONS

The jvmsnap 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.

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

-sC
Specify the character used to separate the name from the value in the output. The default separator is the space character.

-v
Verbose output. This option cause the jvmsnap command to include the type and variability of each instrumentation object.

-names name,[name]
Specify the instrumentation objects of interest. In terms of a Java regular expression, the default output of the jvmsnap 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 in the Pattern class introduced in J2SE 1.4.0.

OUTPUT FORMAT

The output of the jvmsnap command is a list of zero or more name/value pairs. The output follows the following pattern:
[ name separator_character value [ type variability ] ]*

Where separator_character is the space character by default or the character indicated by the -s option. No white space is inserted before or after the separator character. However, white space is inserted between the value and type fields and between the type and variability fields.

The output format of the jvmsnap command is variable and depends on the available instrumentation in the target Java Virtual Machine.

EXAMPLES

To take a snapshot of the instrumentation available in 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 jvmsnap 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.

% jvmsnap -list 21891
hotspot.ci.native.compiles
hotspot.ci.native.time
hotspot.ci.nmethod.codesize
hotspot.ci.nmethod.size
hotspot.ci.osr.bytes
hotspot.ci.osr.compiles
...

Snapshot all instrumentation

This example shows a simplistic use of the jvmsnap command. This example attaches to lvmid 21891 and takes a snapshot of all the available instrumentation objects.

% jvmsnap 21891
... output omitted

Snapshot all instrumentation for a remote Java Virtual Machine

This example attaches to lvmid 40496 on the system named remote.domain and takes a snapshot of all its available instrumentation.

% jvmsnap 40496@remote.domain
... 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 host. The perfagent is located using the rmiregistry on remote.domain that is bound to the default rmiregistry port (port 1099).

Snapshot specific instrumentation objects

This example attaches to lvmid 21891 and take a snapshot of two specific counters.

% jvmsnap -names "hotspot.ci.total.compiles|hotspot.ci.total.time" 21891
hotspot.ci.total.compiles=78
hotspot.ci.total.time=5316274102 

Snapshot specific instrumentation object specified by pattern

This example attaches to lvmid 21891 and takes a snapshot of samples of all the Eden space related counters.

% jvmsnap -names "hotspot.\S*.eden.\S*$" 21891
hotspot.gc.new.eden.capacity=2097152
hotspot.gc.new.eden.invocations=241
hotspot.gc.new.eden.time=556551182
hotspot.gc.new.eden.used=1932424 

SEE ALSO


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

Sun
Java Software