Heapster Agent

Once you have downloaded the Heapster distribution, extract the zip file and locate the discotek.heapster.agent-1.x.jar file. This is the agent file that integrates into the JVM running your application. You will need to modify the command line that invokes the JVM to include the following parameter:

-javaagent:<path to agent jar>=<path to configuration file>

The configuration file has the following properties:

The server-port tells Heapster which port to use to listen to client requests. The Heapster client is run in a separate JVM and allows the user to make queries into the host JVM, where Heapster is collecting heap data. The server-port property is optional. If not defined, the default port is 8888.

The inclusion property is a Java regular expression which defines the class name space for which Heapster will collect heap data. If your company is Example Inc., you would probably use an inclusion such as com.exampleinc.* or com\.exampleinc\..*. Note, both expressions would probably be adequate, but the second is a stricter Java regular expression, while the first has more readability.

The exclusion property is also a Java regular expression, but defines the class name space to be excluded from heap data collection.

The inclusion property is mandatory, but the exclusion property is not. Here are the rules which Heapster uses to include classes:

  1. You must define one or more inclusion properties (but should define at least one).
  2. You may define zero or more exclusion properties.
  3. Exclusions simply subtract from the inclusion name space. For example, exclusion=com.exampleinc.test.*, would exclude class com.exampleinc.test.SampleTest from inclusion=com.exampleinc.*

The server-address property is only used by the client. It should only be necessary if you are running the Heapster client on a different machine thant than the Heapster agent. The value can be a name or an IP address.

Heapster Client

The Heapster Client allows you to make queries into the JVM to examine heap data. Here is a screen shot of the client before any data is loaded:

The syntax for invoking the client is as follows:

java ca.discotek.heapster.client.gui.HeapsterClient <path to configuration file>

The configuration file parameter is optional. If not supplied, the Heapster client will assume you are connecting to a Heapster agent on localhost on port 8888. The Heapster client configuration file has the exact same syntax as the Heapster agent configuration file (discussed above). If you are running both the agent and the client on the same machine, it makes sense for both to point to the same configuration file. You should note, if you are running both on the same machine, you can forego using a configuration file altogether if you are content to use the default port of 8888.