Solaris and Linux Installation Instructions

J2SE Installation

If you have not already downloaded and installed the J2SE 5.0 JDK, please do so now. Follow the J2SE 5.0 JDK download and installation instructions. Once you have a working J2SE 5.0 JDK installation, continue with jvmstat Tools Installation. Note that the J2SE 5.0 JRE does not contain the class files need to run the jvmstat 3.0 tools. You must download the J2SE 5.0 JDK to run the jvmstat 3.0 tools.

jvmstat Tools Installation

The jvmstat tools distribution is released in both tar and zip formats. There is a single distribution for all supported platforms. These instructions will guide you though the installation process using the Korn Shell on Solaris, Linux, and for the Korn Shell in the MKS Tookit for Windows. Every effort has been made to use shell commands that are compatible with both the Bourne and Korn shells. You may need to adapt these instructions to your preferred shell.

To use the tar archive, you must have a tar executable on your system. Similarly, to use the zip format, you need to have an unzip executable on your system. The jar command can be used in place of the unzip command, as jar files are an extension of zip archives. In any case, these instructions assume that the necessary 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; however, they are not required for proper installation or operation of the jvmstat tools.

Step 1: Open a shell window

The first step is to open a cmdtool, dtterm, or xterm window. In this windows, set your PATH environment variable to include the directory to the necessary tar, unzip, or jar executable:

> PATH=$PATH: <path to tar/unzip directory>
> export PATH

If you plan to use the jar command in the Java 2 JDK, make sure the bin directory for the JDK is in your PATH:

> PATH=$PATH: JAVA_HOME/bin
> export PATH

The above assumes that a version of the J2SE JRE or JDK is not already found in the user's PATH.

For the MKS Korn shell, the path seperator characher must be changed from the colon character ( :), to an escaped semi-colon character ( \;). For example:

> PATH=$PATH\; <path to tar/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 /home/user and that the jvmstat-3.0_b03.tar or 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 .

Step 3: Install the jvmstat distribution

To install the distribution, perform the following steps.

Change your working directory to the installation directory.

> cd /home/user

Verify that either the .zip or .tar jvmstat distribution file is located in the current directory:

> ls -l
-rw-r--r-- 1 user grp 344576 Aug 15 17.38 jvmstat-3.0_b03.tar
-rw-r--r-- 1 user grp 148461 Aug 15 17.38 jvmstat-3.0_b03.zip

Install the distribution.

If you are installing the tar file, enter the following

> tar xf jvmstat-3.0_b03.tar

If you are installing the zip file, enter the following

> unzip jvmstat-3.0_b03.zip

These commands 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.tar jvmstat-3.0_b03.zip

After the archive files are deleted or moved to a new location, the JVMSTAT_HOME directory will contain the following directories.

> ls -FC jvmstat
bat/ bin/ docs/ etc/ jars/

Step 4: Set Environment Variables

The scripts provided with the jvmstat distribution rely only upon the PATH environment variable. The PATH environment variable must be changed to include the jvmstat bin and the J2SE 5.0 SDK bin directories. If the java executable is found in a directory in the PATH other than a J2SE 5.0 SDK, so as the /bin or /usr/bin directories, then the scrupt will not be able to locate the tools.jar archive and will fail to launch the tools.

Set your PATH variable to include the jvmstat and J2SE 5.0 SDK 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

Step 5: Install the jstatd policy file

The jstatd tool is an RMI based server that ships with the J2SE 5.0 SDK 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 J2SE 5.0 jstatd documentation describes a simpile 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.

Step 6: Test the installation

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 decribed 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.

Trouble Shooting

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 experencing, then send an e-mail to jvmstat-support@sun.com. Please include the J2SE 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)