(c) 2012 Nastel Technologies, Inc. All rights reserved.

AutoPilot(R) Heap Detective(TM)
Version 1.0.1

About AutoPilot(R) Heap Detective(TM)
-------------------------------------
AutoPilot(R) Heap Detective(TM) is a tool designed for Java developers to 
analyze JVM heap remotely on any running JVM without having to generate 
heap dump files. This tool can be used to spot memory leaks, diagnose memory
problems and help optimize Java application memory footprint.

Features:
	* Analyze Java heap remotely
	* Force GC (garbage collection) remotely
	* Show JVM summary: all Java properties, heap usage, free memory
	* Show allocated classes: instance counts, byte counts, avg. size
	* Drill down to areas where memory is used by Instance Count,
			Retained Size, Shallow size
	* Drill down to what objects hold references to top memory consumers
	* Take and compare multiple heap snapshots

AutoPilot(R) Heap Detective(TM) can be upgraded to AutoPilot M6 
Enterprise (http://www.nastel.com/products/autopilot-m6.html) for
production level monitoring and diagnostics of Java, .NET, and middleware 
including deep dive into transactions.  

AutoPilot(R) Heap Detective(TM) consists of 2 components:
   * Heap Detective JVM Agent: shared library loaded into Java VM, which 
					listens on a specified TCP port (default 16400).
   * Heap Detective UI: Java application (UI) which connects to JVM Agent 
					via TCP to retrieve and process data gathered by JVM Agent.

NOTE: Taking heap snapshots will pause the target VM for a period of time 
which may range from a few seconds to a few minutes. The duration of the 
pause will depend on the used heap size (larger heaps take longer to process).


System Requirements
-------------------
	Heap Detective JVM Agent:
		* SUN JRE 1.6, 1.7 (32- or 64-bit)
		* Windows XP SP3, 7, 2008 (32- or 64-bit)
		* Linux with glibc 2.4 or higher (32- or 64-bit)
	
	Heap Detective UI:
		JRE 1.6 or higher


Loading Heap Detective JVM Agent
--------------------------------
To have the JVM Agent loaded into JVM, add the following option to JVM startup:

	-agentpath:<PATH-TO-JVM-AGENT>[=<JVM_AGENT_OPTION> [,<JVM_AGENT_OPTION>]...]

where
	* <PATH-TO-JVM-AGENT> is the path to the appropriate shared library for the JVM
		Agent based on platform and type of JVM (currently, only Windows and Linux are supported).
	* <JVM_AGENT_OPTIONS> are options to pass to JVM Agent.  Options have the form: name=value.
		Multiple options are separated by commas.  The JVM Agent supports the following options
		(<APHD_INST_DIR> represents the installation directory for Heap Detective):

			cfgfile: path to JVM Agent configuration file (default: <APHD_INST_DIR>/config/aphdjagent.properties)
			port:    port number to listen on for UI connections (default: 16400)

For example, to load the JVM Agent using default configuration,
invoke the JVM as follows:

	Windows(x64): java -agentpath:<APHD_INST_DIR>\JvmAgent\windows\x64\aphdjagent.dll ...
	Windows(x86): java -agentpath:<APHD_INST_DIR>\JvmAgent\windows\x86\aphdjagent.dll ...
	Linux  (x64): java -agentpath:<APHD_INST_DIR>/JvmAgent/linux/x64/aphdjagent.so ...
	Linux  (x86): java -agentpath:<APHD_INST_DIR>/JvmAgent/linux/x86/aphdjagent.so ...

To include JVM Agent options, invoke JVM as follows:

	Windows: java -agentpath:<APHD_INST_DIR>\JvmAgent\windows\x64\aphdjagent.dll=port=12345,cfgfile=<APHD_INST_DIR>\config\myagent.properties ...
	Linux  : java -agentpath:<APHD_INST_DIR>/JvmAgent/linux/x64/aphdjagent.so=port=12345,cfgfile=<APHD_INST_DIR>/config/myagent.properties ...
	
The UI connects to the JVM Agent via TCP. If connecting to a remote JVM, the port must be
accessible from the remote system.  This may require updating firewall(s) to allow remote
access to this port.


Launching Heap Detective User Interface
---------------------------------------
Windows:
To launch the user interface, execute the file: <APHD_INST_DIR>\aphd-ui.bat.  

Linux (requires X Windows):
To launch the user interface, execute the file: <APHD_INST_DIR>/aphd-ui.sh (script requires bash shell).
If bash is not available, launch UI as follows: java -Xms1024m -Xmx2048m -jar <APHD_INST_DIR>/UI/ap-heap-detective.jar

It prompts for the host and port on which the JVM Agent is listening for 
connections. Enter the appropriate information to establish a session with 
JVM Agent.

NOTE: You may need to adjust startup VM heap parameters when launching 
Heap Detective UI in order to handle heap snapshots from large VMs. 
By default the UI comes -Xms1024m -Xmx2048m. Increase heap size accordingly 
when handling heap snapshots from large VM instances.
