Performance Co-Pilot PMDA for Monitoring the Java Virtual Machine
=================================================================

This PMDA is capable of collecting statistics from running Java
virtual machines (JVM) via the jstat(1) program.

There is one instance of the metrics for each JVM process found
by the jps(1) command, which is part of the Java Development Kit
(as is jstat(1) itself).

Metrics
=======

The file ./help contains descriptions for all of the metrics exported
by this PMDA.

Once the PMDA has been installed, the following command will list all
the available metrics and their explanatory "help" text:

	$ pminfo -fT jstat

Installation
============

 +  Verify that the jps(1) command produces a list of interesting Java
    processes which you'd like to monitor.

 +  # cd $PCP_PMDAS_DIR/jstat

 +  Check that there is no clash in the Performance Metrics Domain
    defined in ./domain.h and the other PMDAs currently in use (see
    $PCP_PMCDCONF_PATH).  If there is, edit ./domain.h to choose another
    domain number.

 +  The jstat PMDA is one that polls the virtual machines and caches the
    most recent value for the performance metrics.  The cached values
    are the ones returned via the PMCD to clients requesting jstat
    performance metrics.  The default polling rate is once every five
    seconds to each virtual machine being monitored; if you wish to
    change this, edit Install and change the value of pollrate near the
    start of the script.

 +  Then simply use

	# ./Install

    and choose both the "collector" and "monitor" installation
    configuration options.

De-installation
===============

 +  Simply use

	# cd $PCP_PMDAS_DIR/jstat
	# ./Remove

Troubleshooting
===============

 +  After installing or restarting the agent, the PMCD log file
    ($PCP_LOG_DIR/pmcd/pmcd.log) and the PMDA log file
    ($PCP_LOG_DIR/pmcd/jstat.log) should be checked for any warnings
    or errors.

 +  The jps(1) program will give a list of java processes for which
    the jstat(1) program will work.  Both need to be run with the
    appropriate level of privileges.
