If you have not already downloaded and installed the Java SE 5.0 or later JDK, please do so now. Once you have a working Java SE 5.0 or later JDK installation, continue with jvmstat Tools Installation. Note that the Java SE JRE does not contain the class files need to run the jvmstat 3.0 tools. You must download the Java SE JDK to run the jvmstat 3.0 tools.
The jvmstat tools distribution is released as a single zip archive for all platforms. These instructions will guide you through an installation using basic Bourn Shell syntax, which is applicable to Solaris, Linux, and the MKS Toolkit on Windows. You may need to adapt these instructions to your preferred shell.
To install the zip archive, you must have an unzip executable on
your system. Most Solaris and Linux system have the zip package preinstalled.
However, if your system does not include the zip package, it is available
for multiple platforms
here.
These instructions assume that the unzip executable can be
found in a directory included in the user's PATH
environment variable.
In the following instructions, the > character represents
the shell's command prompt and the commands you enter to the shell are
indicated by text typeset in bold. These instructions will also
contain references to JVMSTAT_HOME
and JAVA_HOME strings.
Although these appear to be environment variables at first glance,
they are intended to be substituted with the paths to the installation
directories for jvmstat and the Java 2 JDK, respectively. You may choose
to create environment variables with these names, but they are not
required for proper installation or operation of the jvmstat tools.
However, properly setting the PATH
environment variable,
and in most cases the JVMSTAT_JAVA_HOME
environment
variable, is required.
The first step is to open a cmdtool, dtterm, or xterm window. In this
window, set your PATH
environment variable to include the
directory containing the unzip executable:
> PATH=$PATH:<path to unzip directory>
> export PATH
For the MKS Korn shell, the path separator character must be changed from the colon character (:), to an escaped semi-colon character (\;). For example:
> PATH=$PATH\;<path to unzip directory>
The next step is to select an installation directory. Select any directory for which you have the appropriate permissions to create files and directories. These instructions will assume that you selected /home/user and that the jvmstat-3.0_b03.zip distribution file is located in this directory. Installing the jvmstat distribution will result in the creation of a jvmstat subdirectory containing the entire distribution. The instructions will refer to the /home/user/jvmstat directory as JVMSTAT_HOME.
To install the distribution, perform the following steps.
Change your working directory to the installation directory.
> cd /home/user
Verify that the .zip jvmstat distribution file is located in the current directory:
> ls -l
-rw-r--r-- 1 user grp 148461 Aug 15 17.38 jvmstat-3.0_b03.zip
To install the zip archive using the unzip command, enter the following:
> unzip jvmstat-3.0_b03.zip
The unzip command will extract the distribution from the archive file and install it in the jvmstat subdirectory. At this time, the distribution file is no longer needed. You can delete it or move it to another location.
> rm jvmstat-3.0_b03.zip
After the archive file has been deleted or moved to a new location, the JVMSTAT_HOME directory will have the following contents:
> ls -FC jvmstat
LICENSE README bat/ bin/ docs/ etc/ jars/
There are two environment variables that need to be set before running
the jvmstat 3.0 tools. The PATH
environment variable and
the JVMSTAT_JAVA_HOME
environment variable. The PATH
environment variable needs to be set to include the path to the Java SE 5.0
or later JDK bin directory and the path to the jvmstat 3.0 bin
directory.
Set your PATH
variable to include the jvmstat and
Java SE 5.0 or later JDK bin directories:
> PATH=JVMSTAT_HOME/bin:JAVA_HOME/bin:$PATH
> export PATH
If you are using the MKS Tookit on Windows for your installation, the above commands must be entered as follows:
> PATH=JVMSTAT_HOME/bin\;JAVA_HOME/bin\;$PATH>
> export PATH
The JVMSTAT_JAVA_HOME
environment variable must be set
to the path to the Java SE 5.0 or later JDK bin directory. In some
cases, the scripts will be able to automatically set this variable for you.
However, if an installed JDK or JRE is found in the PATH
before JAVA_HOME/bin/java
, such as in /bin/java
or /usr/bin/java
, the jvmstat scripts will not correctly
set the JVMSTAT_JAVA_HOME
environment variable. In such
cases, the scripts will issue an error message indicating that the
JVMSTAT_JAVA_HOME
environment variable must be explicitly
set by the user.
Set the JVMSTAT_JAVA_HOME
environment variable as follows:
> JVMSTAT_JAVA_HOME=JAVA_HOME
> export JVMSTAT_JAVA_HOME
If you still get error messages after setting JVMSTAT_JAVA_HOME
,
please verify that the JVMSTAT_JAVA_HOME
environment variable
is set to the top level directory of a Java SE 5.0 or later JDK installation
and that the $JVMSTAT_JAVA_HOME/lib/tools.jar
file exists.
The jstatd tool is an RMI based server that ships with the Java SE 5.0 or later JDK and allows the various jvmstat tools to remotely monitor target JVM processes. By default, the jstatd server installs an instance of the RMI security manager and therefore requires a security policy file. The Java SE 5.0 jstatd documentation describes a simple security policy that provides unlimited access to classes loaded from the tools.jar archive.
First, create a file called jstatd.policy using your favorite text editor. The file should contain the following text:
grant codebase "file:${java.home}/../lib/tools.jar" {
permission java.security.AllPermission;
};
The jstatd.policy file can reside in any directory you choose. The instructions that follow assume that the jstatd.policy file is located in the /home/user directory.
Now that your jvmstat distribution is installed and configured, let's run some tests.
Simple Test
The first test is a simple test that verifies that the bundled jstat tool is working as expected. This test runs the jstat command such that it attaches to its own JVM, by specifying 0 as the lvmid of the target process, and takes 3 samples of the instrumentation at 1000 millisecond intervals.
> jstat -gcutil 0 1000 3
S0 S1 E O P YGC YGCT FGC FGCT GCT
0.00 0.00 37.20 55.10 15.77 106 0.174 58 5.268 5.442
0.00 0.00 45.87 55.14 15.77 106 0.174 59 5.357 5.531
0.00 0.00 96.42 55.14 15.77 106 0.174 59 5.357 5.531
The output from the jstat command should be similar to the output shown above. If an error message or exception is output, then proceed to the trouble shooting section below.
Local Test
This test uses the jstat and visualgc commands to monitor another Java application. In this test, we will start up a Java application, determine its lvmid with the jps command, and then connect to the target JVM with both the jstat and visualgc commands.
Begin by starting up your target Java application. Any 1.4.2 or later Java application will work. This example uses the Java2Demo application.
> java -jar JAVA_HOME/demo/jfc/Java2D/Java2Demo.jar
Once the target Java application is running, execute the jps command from a separate cmdtool, dtterm, or xterm windows and find the lvmid for the target JVM. Remember, you need to set the PATH environment variable in this new window as described in Set Environment Variables section above.
> jps
23551 Java2Demo.jar
23581 Jps
It's typical to see Jps listed in the output of the jps command. Next, run jstat, telling it to monitor lvmid 23551, taking 3 samples at one second intervals:
> jstat -gcutil 23551 1000 3
The output from jstat is omitted here; however, it should be similar to the output observed in the Simple Test section above.
Now, run visualgc telling it to monitor lvmid 23551:
> visualgc 23551
Two or three windows will appear (depending on which garbage collection policy is in effect). The following two windows will appear regardless of the garbage collection policy:
Descriptions of the various panels in these windows are provided in the visualgc manual page. If an error message or exception is output, then proceed to the trouble shooting section below.
Remote test
This test will verify that the remote monitoring functionality is working. This test can be run on one system, but it is better to run it on two systems. For a two system test, you will need to perform the installation of the jvmstat tools on the second system before proceeding with this test.
For this test, we will assume that the system names are monitored for the system running the target application and monitoring for the system running the jvmstat tools.
On monitored, startup the jstatd server and the target Java application. Once again, we will use the Java2Demo application as our target Java application. The jstatd server is started as follows:
> jstatd -J-Djava.security.policy=/home/user/jstatd.policy
Now, from a cmdtool, dtterm, or xterm window on monitoring, run the jps command to discover the lvmis of the target Java application. Substitute the name of your monitored system for monitored in the following commands.
> jps monitored
17869 Java2Demo.jar
17876 Jstatd
17877 Jps
It's typical to see both Jps and Jstatd listed in the output of the jps command. Next, run jstat, telling it to monitor lvmid 17869 on the system named monitored, taking 3 samples at one second intervals.
> jstat -gcutil 17869@monitored 1000 3
The output from jstat is omitted here; however, it should be similar to the output observed in the Simple Test section above.
Now, run visualgc telling it to monitor lvmid 17869 on the system named monitored:
> visualgc 17869@monitored
Two or three windows will appear as described in the Local Test section above.
Terminating Processes
You may want to terminate the processes we started in the above tests. The jstatd process can be terminated as follows:
> kill 17876
Where 17876
is
the process id reported by the native ps command or the
lvmid reported by the jps command as shown above.
If you experience error messages or exceptions from any of the jvmstat tools, check that your PATH variable is set correctly. Also, check the manual pages for the tools for proper usage. If these suggestions do not resolve your problems, consult the jvmstat FAQ. If the jvmstat FAQ does not provide a resolution for the problem you are experiencing, then send an e-mail to jvmstat-support@sun.com. Please include the JDK version information (java -version) and the jvmstat version information (visualgc -version) in the e-mail along with a description of the problem you are experiencing.