If you have not already downloaded and installed the J2SE 1.4.2 SDK or JRE, please do so now. Follow the J2SE 1.4.2 download and installation instructions. Once you have a working J2SE 1.4.2 installation, continue with jvmstat Tools Installation.
The jvmstat tools distribution is released in both tar and zip formats. There is a single distribution that contains everything needed to run the tools on 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 SDK or JRE, respectively. You may choose to create environment variables with these names; however, they are not required for the installation or operation of the jvmstat tools.
The first step is to open a cmdtool, dtterm, or xterm window. Next, select the command prompt window and set your PATH environment variable to include the directory to the necessary tar, unzip, or jar binary:
>
PATH=JAVA_HOME/bin:$PATH:<path to tar/unzip
directory>
For the MKS Korn shell, the PATH must be entered as follows:
>
PATH=JAVA_HOME/bin\;$PATH\;<path to tar/unzip directory>
If you plan to use the jar command in the Java 2 SDK, make sure the bin directory for the SDK is in your PATH:
>
PATH=JAVA_HOME/bin:$PATH
The
JAVA_HOME/bin
is added before the existing PATH because the existing PATH may
already contain a Java 1 or Java 2 installation that you might not
want to use.
The first 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.tar or jvmstat.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 jvmstat distribution is located in the current directory.
>
ls -l
total 288
-rw-r--r-- 1 user grp 134656 Jul 23
10:07 jvmstat.tar
Install the distribution.
If you are installing the tar file, enter the following
>
tar xf jvmstat.tar
If you are installing the zip file, enter the following
>
unzip jvmstat.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.jar jvmstat.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/ classes/ docs/ etc/ policies/
The scripts provided with the jvmstat distribution rely upon the availability of certain shell environment variables. In this step, these environment variables are set.
Set your PATH variable to include the jvmstat and J2SE 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 perfagent is an RMI based server that allows the various jvmstat tools to remotely monitor target JVM processes. Because this is an RMI server, a security policy must be provided to the server application. The distribution includes three policy file templates and an application to transform these templates into working policy files. The following table describes the template files provided with the distribution.
Template File |
Description |
PerfAgentAll.tmpl |
A template file for configuring a policy that grants full access privileges to the perfagent server. |
PerfAgentMinimal.tmpl |
A template file for configuring a policy that grants the minimum privileges needed by the perfagent server to run in most environments. The granted privileges allow a client from any host to connect to the perfagent server. See the PerfAgentTrustedHost.tmpl file for how to limit access to selected, trusted hosts. |
PerfAgentTrustedHost.tmpl |
A template file for configuring a policy similar to the PerfAgentMinimal.tmpl policy. This template includes entries that limit access to selected, trusted hosts. |
The working policy files must be based on the jvmstat installation directory. This task is accomplished by running the configurepolicy tool on each of the template files. Configure the files by running the following commands:
>
cd JVMSTAT_HOME/policies
> configurepolicy PerfAgentAll.tmpl PerfAgentAll.policy
> configurepolicy PerfAgentMinimal.tmpl PerfAgentMinimal.policy
> configurepolicy PerfAgentTrustedHost.tmpl PerfAgentTrustedHost.policy
The tool substitutes full strings for various jvmstat pseudo properties included in the template files. The output generated by the tool is a working policy file for the platform on which it was generated based on the jvmstat installation location.
A security policy needs to be chosen for the perfagent server. You can choose to customize the template files or the generated policy files or use them as is. If you customize a template file, be sure to regenerate the corresponding policy file by rerunning the configurepolicy tool. In order to activate a given security policy for the perfagent server, you need to copy a working policy file into the PerfAgent.policy file. The following commands need to be run to activate the PerfAgentMinimal.policy file:
> cd
JVMSTAT_HOME/policies
> cp
PerfAgentMinimal.policy PerfAgent.policy
Select an alternative policy file as the source file of the above copy command if you wish to active a different security policy.
Alternatively, you can set and export the PERFAGENT_POLICY environment variable to the path to your chosen policy file. This mechanism is useful for testing various policy files prior to selecting one as your default policy.
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 things are installed correctly. This test runs the jvmstat command such that it attaches to its own JVM, by specifying 0 as the target process id, and takes 3 samples of the instrumentation, at 1000 millisecond intervals.
>
jvmstat -gcutil 0 1000 3
S0 S1 E O P EGC OGC GCT
0.00 0.00 45.87 0.00 39.93 0 0 0.000
0.00 0.00 46.71 0.00 40.55 0 0 0.000
0.00 0.00 47.51 0.00 40.55 0 0 0.000
The output from the jvmstat command should be similar to the output shown above.
Local Test
This test uses the jvmstat command to monitor another Java application. In this test, we will start up a Java application, determine its process id with the jvmps command, and then connect to the target JVM with the jvmstat command.
Begin by starting up your target Java application. Any 1.4.2 compatible 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 jvmps command from a separate cmdtool, dtterm, or xterm windows and find the process id for the target JVM. Remember, you need to set the PATH environment variable in this new window as described in Set Environment Variables above.
>
jvmps
23551 /usr/j2se/demo/jfc/Java2D/Java2Demo.jar
23581
/usr/local/jvmstat/classes/jvmps.jar
It's typical to see jvmps.jar listed in the output of the jvmps command. Next, run jvmstat, telling it to monitor process id 23551, taking 3 samples at one second intervals.
>
jvmstat -gcutil 23551 1000 3
The output from jvmstat is omitted here; however, it should be similar to the output observed above for the simple test.
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 perfagent server and the target Java application. The perfagent server is started as follows:
> perfagent
Now, from a cmdtool, dtterm, or xterm window on monitoring, run the jvmps command to discover the process id of the target Java application. Substitute the name of your monitored system for monitored in the following commands.
> jvmps
monitored
17869 /usr/j2se/demo/jfc/Java2D/Java2Demo.jar
17876
/usr/local/jvmstat/classes/perfagent.jar
It's typical to see perfagent.jar listed in the output of the jvmps command. Next, run jvmstat, telling it to monitor process id 17869 on the system named monitored, taking 3 samples at one second intervals.
>
jvmstat -gcutil 17869@monitored 1000 3
The output from jvmstat is omitted here; however, it should be similar to the output observed above for the simple test.
Terminating Processes
You may want to terminate the processes we started in the above tests. The perfagent process can be terminated as follows:
> kill
17876
Where
17876
is
the process id reported by the native ps command or by the
jvmps command as shown above.
Troubleshooting
If at any time you experience exceptions being thrown, check that your PATH variable is set correctly and is finding the correct version of the jvmstat tools and J2SE. If this does not resolve the problem, or if other problems persist, verify that the distribution was properly installed and configured and reinstall if necessary. If problems continue to persist, consult the jvmstat FAQ or send mail to jvmstat-support@sun.com.