Windows Installation Instructions

Java SE Installation

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 JDK installation, continue with jvmstat Tools Installation. Note that the Java SE 5.0 or later JRE does not contain the class files needed to run the jvmstat 3.0 tools. You must download the Java SE 5.0 or later JDK to run the jvmstat 3.0 tools.

Please note that the HotSpot JVM instrumentation is not accessible on Windows 95, 98, or ME platforms. Therefore, the jvmstat tools can only monitor HotSpot JVMs running on the Windows NT 3.1 and later platforms. In addition, the HotSpot JVM instrumentation is not accessible on Windows NT based systems where the application's temporary directory is stored on a FAT type file system, as such file systems provide insufficient security controls. Please consult the jvmstat FAQ for work-around solutions.

jvmstat Tools Installation

The jvmstat tools distribution is released as a single zip archive for all platforms. These instructions will guide you through an installation using the DOS Command tool. If you have the MKS toolkit package installed on your Windows system, you can choose to follow the Solaris and Linux installation instructions instead.

To install the zip archive, you must have an unzip executable on your system. The zip package is available for multiple platforms here. These instructions assume that the unzip.exe executable can be found in a directory included in the user's PATH environment variable.

In the following instructions, text such as C:\> or C:\jvmstat> represent the DOS command tool prompt. Text following these prompts that represent commands you need to type 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 of the PATH environment variable, and in most cases the JVMSTAT_JAVA_HOME environment variable, is required.

Step 1: Open a DOS Command Prompt window

The first step is to open a DOS command prompt window. The location of this command is different depending on the Windows NT variant that you are using. Look for this command in Start->Programs->Command Prompt or Start->Programs->Accessories->Command Prompt. Next, select the command prompt window and set your PATH environment variable to include the directory containing the unzip.exe executable.

C:\> SET PATH=%PATH%; <path to unzip directory>

Step 2: Select Installation 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 C:\ as the installation directory 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 C:\jvmstat directory as JVMSTAT_HOME .

Step 3: Install the jvmstat distribution

To install the distribution, perform the following steps.

Change your working directory to the installation directory.

C:\> cd c:\

Verify that the jvmstat distribution is located in the current directory.

C:\> dir
08/13/2004 5.58p 148,461 jvmstat-3.0_b03.zip

To install the zip archive using the unzip command, enter the following:

C:\> 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.

C:\> del 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:

C:\gt; dir /w jvmstat
[.] [..] [bat] [bin] [docs] [etc] [jars] LICENSE README

Step 4: Set Environment Variables

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 bin directory and Java SE 5.0 or later JDK bin directory.

C:\> SET PATH= JVMSTAT_HOME\bat; JAVA_HOME\bin;%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 C:\Windows\System32\java.exe is found in the PATH before JAVA_HOME\bin\java.exe , which can happen when a public JRE or JDK has been installed, 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:

C:\> SET JVMSTAT_JAVA_HOME= JVMSTAT_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.

Step 5: Install the jstatd policy file

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 C:\ directory.

Step 6: Test the installation

Now that your jvmstat distribution is installed and configured, let's run a couple of tests.

Simple Test

The first test is a simple test that verifies that the bundled jstat tools 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.

C:\> 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 Troubleshooting 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.

C:\> java -jar JAVA_HOME\demo\jfc\Java2D\Java2Demo.jar

Once the target Java application is running, execute the jps command from a separate Command Prompt window 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.

C:\> 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:

C:\> 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:

C:\> 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:

C:\> jstatd -J-Djava.security.policy=C:\jstatd.policy

Now, from another Command Prompt window on the monitoring, run the jps command to discover the lvmid of the target Java application. Substitute the name of your monitored system for monitored in the following commands.

C:\> 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 process id 23551 on the system named monitored, taking 3 samples at one second intervals.

C:\> 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:

C:\> 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 must be terminated using the Windows Task Manager. You can use the lvmid reported by the jps command or attempt to identify the process directly in the Windows Task Manager process list. See your Windows documentation for information on accessing and using the Task Manager.

Troubleshooting

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.


Left Curve
Java SDKs and Tools
Right Curve
Left Curve
Java Resources
Right Curve
JavaOne Banner Java 8 banner (182)