JVMPI Agent
Purpose
The JVMPI Agent is a dynamic library that is part of the J2SE and J2ME virtual machine distributions. The Agent ensure the memory profiling functionality when using the Memory Profiling feature for Java.
Syntax
java -Xint -Xrunpagent[:<options>] <configuration>
where:
<options> are the command line options of the JVMPI agent
<configuration> is the configuration required to run the application
Description
Because of the garbage collector concept used in Java, Performance Profiling for Java uses the JVMPI agent facility delivered by the JVM. This differentiates Memory Profiling for Java from the SCI instrumentation technology used with other languages.
To run the JVMPI Agent from the command line, add the -Xrunpagent option to the Java command line.
The JVMPI Agent analyzes the following internal events of the JVM:
Method entries and exits
Object and primitive type allocations
The JVMPI Agent retrieves source code debug information during runtime. When the Agent receives a snapshot trigger request, it can either execute an instantaneous JVMPI dump of the JVM memory, or wait for the next garbage collection to be performed.
Note Information provided by the instantaneous dump includes actual memory use as well as intermediate and unreferenced objects that are normally freed by the garbage collection.
The actual trigger event can be implemented with any of the following methods:
A specified method entry or exit used in the Java code
A message sent from the Snapshot button or menu item in the graphical user interface
Every garbage collection
The JVMPI Agent requires that the Java code is compiled in debug mode, and cannot be used with Java in just-in-time (JIT) mode.
Options
The following parameters can be sent to the JVMPI Agent on the command line.
-H_Cx=<size>
-H_Ox=<size>
Specifies the size of hashtables for classes (-H_Cx) or objects (-H_Ox) where <size> must be 1, 3, 5 or 7, corresponding respectively to hashtables of 64, 256, 1024 or 4096 values.
-JVM <prefix>
By default, the Agent waits for the virtual machine (VM) to be fully initialized before it starts collecting data. This usually relates to the spawning of the first user thread. With the -JVM option, data collection starts on the first memory allocation, even if the VM is not fully initialized.
-N_O
With the -N_O option, the Agent only counts the number of allocated objects and ignores any further object data. The existence of the objects after garbage collection cannot be verified. Use this option to reduce Performance Profiling overhead or to obtain a quick summary.
-D_O_N
Delete Object No. By default, the Agent only collects and presents method data on the latest call to that method. Any further calls to the method replaces existing call data.
Use the -D_O_N option to display all referenced objects.
-D_GC
This option requests a JVMPI dump after each garbage collection
-D_PGC
When using a dump request method, this option makes the Agent wait until the next garbage collection before performing the dump.
-D_M[[<method>,<class>,<mode>],[,<method>,<class>,<mode>]]
Activates "Dump Method" mode.
Use this option to perform a snapshot on entry or exit of the specified methods, where <mode> may be 0 or 1:
0 performs the method dump upon exit
1 performs the method dump on entry
<class> must be the fully qualified name of a class, including the entire package name.
-O_M[[<method>,<class>],[<method>,<class>]]
Activates "Observe Method" mode.
Use this option to store the call stack when the specified methods are called. The stack is loaded from 0 to 10 (max).
-U_S=[<name>]
User name
This option adds the name of the user to the JVMPI dump data. The name must be specified between brackets ("[ ]").
-D_U=[<string>]
This option specifies a start date that is used by the JVMPI dump data. The stringr must be specified between brackets ("[ ]").
-F_M[[<method>,<class>],[<method>,<class>]]
Filter mode.
Use this option to produce JVMPI data only on the specified method(s). All other methods are ignored.
-H_N=[<hostname>]
Hostname.
Use this option to specify a hostname for the JVMPI Agent to communicate with the graphical user interface on the local host. The hostname must be specified between brackets ("[ ]").
-P_T=[<port_number>]
Port number. Use this option to specify a port number for the JVMPI Agent to communicate with the graphical user interface on the local host. The port number must be specified between brackets ("[ ]").
-OUT=[<filename>]
Output filename.
This option specified the name of the trace dump file produced by the JVMPI Agent. Use the Dump File Splitter on this output file to produce a .tsf static trace file for the GUI Memory Profiling Viewer.
Example
The following example launches the JVMPI Agent by dumping the exportvalues and exportvalues2 methods of the com.rational.Th class:
java -Xint -Xrunpagent:-JVM-D_M[[exportvalues,com.rational.Th,0],[exportvalues2,com.rational.Th,0]] -classpath $CLASSPATH Th
Related Topics