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.
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.
The jvmstat distribution is released in both tar and zip formats for all platforms. There is a single distribution that works on 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, as they are applicable to the MKS Toolkit environment.
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, 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 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 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 to the necessary tar, unzip, or jar binary:
C:\>
SET 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:
C:\> SET
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 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.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 C:\jvmstat directory as JVMSTAT_HOME.
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
07/23/2002 01:45p 103,620 jvmstat.zip
07/23/2002
02:09p 134,656 jvmstat.tar
Install the distribution.
If you are installing the tar file, enter the following
C:\>
tar xf jvmstat.tar
If you are installing the zip file, enter the following
C:\>
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.
C:\>
del jvmstat.tar jvmstat.zip
After the archive files are deleted or moved to a new location, the JVMSTAT_HOME directory will contain the following directories.
C:\gt;
dir /w 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
C:\>
SET PATH=JVMSTAT_HOME\bat:%PATH%
C:\> 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:
C:\> cd
JVMSTAT_HOME\policies
C:\jvmstat\policies
>
configurepolicy PerfAgentAll.tmpl PerfAgentAll.policy
C:\jvmstat\policies
>
configurepolicy PerfAgentMinimal.tmpl PerfAgentMinimal.policy
C:\jvmstat\policies
>
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 and based on the temporary directory location, as indicated by the java.io.tmpdir System property. If the %TMP% or %TEMP% environment variables are changed after this command is run, the default setting for java.io.tmpdir may also change. Also, moving an application from one generation of Windows NT to another might also cause the default setting for java.io.tmpdir to change. In these cases, the policy file must be reconfigured by rerunning the configurepolicy commands.
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:
C:\> cd
JVMSTAT_HOME\policies
C:\jvmstat\policies> copy
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 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.
C:\>
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.
C:\>
java -jar JAVA_HOME\demo\jfc\Java2D\Java2Demo.jar
Once the target Java application is running, execute the jvmps command from a separate Command Prompt window 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.
C:\>
jvmps
23551 C:\java\j2sdk1.4.2\demo\jfc\Java2D\Java2Demo.jar
23581
C:\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.
C:\>
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:
C:\>
perfagent
Now, from another Command Prompt window on the monitoring system, 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.
C:\> jvmps
monitored
23551
C:\java\j2sdk1.4.2\demo\jfc\Java2D\Java2Demo.jar
17876
C:\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.
C:\>
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 processes we started in the above tests. The perfagent process must be terminated using the Windows Task Manager. You can use the process id reported by the jvmps command to help identify the appropriate process in the Task Manager process list. See your Windows documentation for information on accessing and using the Task Manager.
Troubleshooting
If at any time you experience error messages from the Command Prompt or 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.