HP

HPjmeter 4.1 User's Guide

English
  HPjmeter 4.1 User's Guide > Chapter 2 Completing Installation of HPjmeter   

Configuring your Application to Use HPjmeter Command Line Options

For most supported versions of Java, it is still necessary to start the application using HPjmeter options on the java command and to modify two environment variables. Or, you may want to use command line options to control the bytecode instrumentation.

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.

To Take Advantage of Dynamic Attach:

Check that JM_JAVA_HOME in $JMETER_HOME/config/hpjmeter.conf is set to a Java 6 directory (6.0.03 or later) to be able to later dynamically attach to a running JVM from the HPjmeter console without first setting HPjmeter options on the command line.

When HPjmeter is installed on a system that has Java 6 installed in the usual location, the installation procedure will automatically store the JDK location in hpjmeter.conf configuration file. If the Java 6.x JDK is installed in a non-standard location, or Java 6.x is installed after HPjmeter is installed, then it is necessary to update the hpjmeter.conf file manually. The typical contents of the file are:

JM_JAVA_HOME=/opt/java6
  1. The HPjmeter installation process will configure JDKs that are installed in the standard location. Some systems have JDKs installed in nonstandard locations, and some applications run with an embedded Java Runtime Environment. In these situations, it is necessary to explicitly indicate 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.

  2. 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.

  3. Specify the HPjmeter switch 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 version of the JVM (using the -d64 option), then you will need to use the 64-bit version of the JVM agent. 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:/opt/hpjmeter/lib/agent.jar -Xrunjmeter myapp  
    NOTE:

    With the addition of JVMTI in JDK 5.0, you can use the -agentlib switch to 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.

  • Using an alternate HPjmeter library to work with applications that are run with the –V2 option on PA systems:

    $ /opt/java1.5/bin/java -V2 –agentlib:jmeter_v2 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

OR

-Xrunjmeter:version.

Selecting Other JVM Agent Options

Add other options using this syntax

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

OR

-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]..., exclude=filter1[:filter2]...

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 BCI Filter icon 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. With HPjmeter 4.0 and later, these filters can also be changed 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:

    $Proxycom.ibm.misc. com.ibm.jvm.com.hp.jmeter.jvmagent. com.hp.jmeter.share.jmx. com.hp.jmeter.asm.

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

    com.jrockit. COM.jrockit. jrockit.COM.rsa.com.sun. java. javax. sun. sunw.io. sunw.util.
    org.apache.org.ietf.org.omg.
    org.w3c.org.xml.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 always include the following packages. They cannot be overriden with an exclude option:

    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 sub-packages 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.

  • An include filter rule will override an exclude filter rule when the same package name is provided on both options, even if one of the options is an implicit default. For example:

    -agentlib:jmeter=exclude=sun.jdbc.odbc:other-package-names

    In this example, the sun.jdbc.odbc package is not excluded because the implicit default include of this package overrides the explicit exclude.

logging=FINEST|FINER|FINE|CONFIG|INFO|WARNING|SEVERE|OFF

Sets a log level for the JVM agent, which allows you to collect varying amounts of information about the node agent and JVM agent. Available log levels in order of impact on performance are:

FINEST (Most impact on performance)
FINER
FINE
CONFIG
INFO
WARNING (Default setting)
SEVERE (Least impact on performance)
OFF (Turn off logging)
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 or using drag and drop. 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. Any console connecting to an application initially started with this agent flag does not enable Java Method HotSpots, and this metric is not listed in the Session Preferences dialog.

Example usage: -agentlib:jmeter=nohotspots

noexception

Reduces dormant overhead by skipping bytecode instrumentation that applies to the Thrown Exception metrics. Any console connecting to an application initially started with this attribute does not enable Thrown Exception metrics, and these metrics are not listed in the Session Preferences dialog.

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

noarrayleak

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

Example usage: -agentlib:jmeter=noarrayleak

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