Configuring your Application to Use the JVM Agent

Start the JVM agent by changing the Java command line for your program and modifying two environment variables.




	NOTE: With the addition of JVMTI in JDK 5.0, you can use of the `-agentlib` switch to help you take advantage of improvements in JDK 5.0 and reduce the impact of data sampling on application performance. While `-Xrunjmeter` can still be used to specify the JVM agent with Java 5 versions, the impact on application performance is significantly greater than when using `-agentlib`. Starting with Java 5.0, `-agentlib` is the standard way to specify the JVM agent. Therefore, this document will refer primarily to `-agentlib.` You will still need to use `-Xrunjmeter` to specify the JVM agent for earlier supported versions of Java (1.4.x).

Preparing to run Java

For most installations, linkage to the appropriate libraries is completed automatically as part of the installation process. Go to step 2 if you have a standard installation of the Java Runtime Environment.

Some applications run with an embedded Java Runtime Environment. In this situation, you will need to correctly identify the location of HPjmeter libraries.
Assuming that JMETER_HOME represents your installation directory, modify the shared library path in your environment as follows:
- On HP-UX running on HP Precision Architecture systems, add $JMETER_HOME/lib/$ARCH to SHLIB_PATH where $ARCH is PA_RISC2.0 or PA_RISC2.0W.
- On HP-UX running on Itanium-based systems with Java 5.x, add $JMETER_HOME/lib/$ARCH to LD_LIBRARY_PATH where $ARCH is IA64N or IA64W.
- On HP-UX running on Itanium-based systems, for JDK 1.4.x versions, use the SHLIB_PATH environment variable to specify the shared library path.
On HP-UX and running Java 1.4.x, specify the Xbootclasspath in your java command.
java -Xbootclasspath/a:$JMETER_HOME/lib/agent.jar ...
On Java 5.0 and later, -Xbootclasspath is optional.

Specify the JVM agent in your java command.

On Java 5.0 and later:

java -agentlib:jmeter[=options] ...

On Java 1.4.x :

java -Xrunjmeter[:options] ...

NOTE: If you use the 64-bit JVM agent, you will need to add -d64 to the JVM command line. For example, type

java —d64 HelloWorld

when SHLIB_PATH is $JMETER_HOME/lib/$ARCH and

where $ARCH equals PA_RISC2.0W or IA64W.

See JVM Agent Options for the list of available options and their descriptions.

Example Usage

Using -agentlib on Java 5.x to run the JVM agent:

 /opt/java1.5/bin/java -Xms256m -Xmx512m -agentlib:jmeter myapp

Setting -Xbootclasspath and using -Xrunjmeter on Java 1.4 to run the JVM agent:

 /opt/java1.4/bin/java -Xms256m -Xmx512m -Xbootclasspath/a:$AGENT \
   -Xrunjmeter myapp

JVM Agent Options

This section provides the list of options for changing the JVM agent behavior and determining the Java version running on the system.

Showing Version Information

To show the version information, use

-agentlib:jmeter=version

-Xrunjmeter:version.

Selecting Other JVM Agent Options

Add other options using this syntax

-agentlib:jmeter[=version] | [=option[,option],*]

-Xrunjmeter[:version] | [:option[,option],*]

where option may be any of these:

appserver_port=port

Associates a port number with a JVM process when it is displayed in the console. This port number is unrelated to the port number used by the node agent, and so it is also unrelated to the optional port number that can be specified in the console when attaching to a managed node.

It does not affect any communication, and is only part of the user interface. The appserver_port= usually corresponds to the port to which the application server listens.
Example usage: -agentlib:jmeter=appserver_port=7001

group_private

Specifies that the JVM will be visible only to node agents run with the same group-id; that is, run by the user belonging to the same group, as the one who runs the JVM. This limitation does not apply to node agents run as root (the installation default). This is the default behavior on HP-UX systems.

You can specify only one of the options owner_private, group_private or public.
Example usage: -agentlib:jmeter=group_private

include=filter1:filter2:...:filtern, exclude=filter1:filter2:...:filtern

Creates a colon-separated list of classes to specify which classes or packages are instrumented. Method-level filtering is not supported.

If a class is not instrumented, the JVM agent metrics that use bytecode instrumentation (BCI) do not provide any output related to the class methods. To see the list of filters in effect while the data was collected, including default agent filters, click the icon when you see it in the console.
Class filtering minimizes the overhead and focuses attention on user-produced code.
By default, the JVM agent instruments bytecode of all loaded classes to implement some of the metrics, except those classes that belong to one of these:
- Application servers, for performance reasons.
- HPjmeter management tools, in order to focus on user-created code.
- A set of implementation-dependent classes that HPjmeter cannot instrument. These cannot be overridden.

Some metrics display results for all classes regardless of filters, because class filters apply only to those metrics that use bytecode instrumentation.




	NOTE: JVM agent filters are distinct from console monitoring filters. For more information, see Setting Monitoring Session Preferences . JVM agent filters are configured when you start the JVM, and cannot be dynamically changed. Console filters are configured when you open a session with a JVM agent, and can be changed from session to session, but not during a session. If the JVM agent has filtered out a class, the console will be unable to see metrics from that class even if you try to remove the console filter for the class.

HPjmeter always excludes these packages:

 com.hp.jmeter.jvmagent.
 org.apache.bcel.
 com.ibm.jvm.
 com.ibm.misc.

The default filters also exclude the following packages. However, you can use the include option to override the default behavior:

 com.jrockit.
 COM.jrockit.
 COM.rsa.
 com.sun.
 java.
 javax.
 jrockit.
 org.apache.
 org.ietf.
 org.omg.
 org.w3c.
 org.xml.
 sun.
 sunw.io.
 sunw.util.
 com.hp.ov.
 i2.

 p0.
 p1.
 weblogic.
 com.bea.
 com.beasys.
 com.ibm.
 com.tivoli.
 org.jboss.
 org.jbossmq.
 org.enhydra.
 org.hsql.
 EDU.oswego.
 com.iplanet.
 com.netscape.server.http.
 com.evermind.
 com.orionserver.
 oracle.

The default filters include these packages. However, you can use the exclude option to override the default behavior.

 sun.jdbc.odbc.
 weblogic.jdbc.informix4.
 weblogic.jdbc.mssqlserver4.
 weblogic.jdbc.oci.
 weblogic.jdbc.rowset.
 com.bea.p13n.
 com.bea.netuix.
 org.apache.jsp.
 org.apache.jasper.

 oracle.jdbc.
 oracle.sql.
 oracle.evermind.sql.
 com.bea.medrec.
 com.ibm.samples.
 com.sun.j2ee.blueprints.
 com.sun.ebank.

You can change the default behavior by using the include option, for example:
-agentlib:jmeter=include=com.ibm.ws,exclude=com.ibm.ws.io
This effect is similar to the previous example, except that the classes belonging to the com.ibm.ws.io package, and its subpackages if any, will be excluded from the instrumentation. Other classes belonging to the com.ibm.ws package or its sub-packages other than io will be instrumented. Classes belonging to sub-packages other than ws of the com.ibm package will be still excluded by the default rule.
In general, you can specify multiple package or class names with the include or exclude option. The behavior with respect to any loaded class will be as defined by the most specific rule (filter) that applies to the fully qualified class name.

monitor_batch[:file=filename]

Enables all metrics and sends the collected data to a file. The default name for the file is javapid.hpjmeter. Use the optional monitor_batch:file=your_file_name to override the default.

Once data has been collected and saved to a file on the managed node, you can view the file from the console using the Open File button. You may need to copy the file to a file system visible from the console. For more information, see Saving Monitoring Metrics Information.
Example usage:
- To use default file name:
  -agentlib:jmeter=monitor_batch
- To specify a file name:
  -agentlib:jmeter=monitor_batch:file=mysaveddata.hpjmeter

noalloc

Reduces dormant overhead by skipping bytecode instrumentation that applies to object allocation metrics: Allocated Object Statistics by Class and Allocating Method Statistics. The noalloc option makes those metrics unavailable.

Example usage: -agentlib:jmeter=noalloc

nohotspots

Reduces dormant overhead by skipping the bytecode instrumentation that supports Java Method Hotspots, which then becomes unavailable for the lifetime of the application. Any console connecting to an application started with this agent flag cannot enable Java Method Hotspots. As a result, this metric is not listed in the open-session dialog.

Example usage: -agentlib:jmeter=nohotspots

noexception

Reduces dormant overhead by skipping bytecode instrumentation that applies to the Thrown Exception metrics. When you specify this option, the Thrown Exception metrics are unavailable in the console for the lifetime of this application.

Example usage: -agentlib:jmeter=noexception

nomemleak

Reduces dormant overhead by skipping bytecode instrumentation that applies to memory leak location events. When you specify this option, the memory leak location alert is unavailable in the console for the lifetime of this application.

Example usage: -agentlib:jmeter=nomemleak

owner_private

Specifies that the JVM is visible only to the node agents run with the same effective user ID; that is, run by the same user as the one who runs the JVM. This limitation does not apply to node agents run as root (the installation default).

You can specify only one of the options owner_private, group_private, or public.
Example usage: -agentlib:jmeter=owner_private

public

Specifies that the JVM is visible to all node agents run on the same host as the JVM.

You can specify only one of the options owner_private, group_private, or public.
Example usage: -agentlib:jmeter=public

verbose[:file=filename]

Prints information about the bytecode instrumentation rules in effect, such as include or exclude settings, and about the individual instrumentation decisions made for all loaded classes. By default, the information is printed on stdout. You can override this by specifying a file name, for example verbose:file=bci.txt.

Example usage: -agentlib:jmeter=verbose

version

Displays the JVM agent version and quits immediately without running any Java applications at all. You cannot use this option with any other options.

Example usage: -agentlib:jmeter=version

JVM Options Usage Examples

Here are some examples of JVM agent option usage:

  -agentlib:jmeter=noalloc,appserver_port=7001,public,include=weblogic:com.bea
  -agentlib:jmeter=nohotspots,owner_private,verbose:file=bcifilters.txt
  -agentlib:jmeter=version
  -agentlib:jmeter=

Configuring your Application to Use the JVM Agent

Technical documentation

» Table of Contents

» Glossary