Profiling a Java application running in Websphere Application Server using PurifyPlus

Technote (FAQ)


How do I profile my Java application running in IBM Websphere Application Server with IBM Rational PurifyPlus?


Java profiling in PurifyPlus version 7.0 for Windows is built using the JVM Profiling Interface (JVMPI). The PurifyPlus JVMPI agent is shipped in the module PureJVMPI.dll which can be found in the Common folder for IBM Rational products (typically C:\Program Files\Rational\Common).

It is important to have the Rational Common folder on the system PATH environment variable, or PurifyPlus may fail to initialize.

There are three ways to enable Websphere Application Server profiling, each with it's own advantages and disadvantages.:

  • Collecting data with the PurifyPlus command line (recommended)
    This is the easiest option to use. The advantages are that you don’t need to undo any changes to switch back to the normal (non-profiling) mode and you can specify additional PurifyPlus options in the same command.
    The disadvantage is that you will get two profiling sessions running. The first session belongs to the Websphere Application Server starter process. This process creates a new JVM which will host Websphere Application Server. It sets up the environment, generates a Java command line from the server settings and ensures the Websphere Application Server process is properly initialized. After that, the starter process terminates. Since the PurifyPlus command line applies to the starter process, both Websphere Application Server and the starter process will be profiled.
    To use this method, you should run the following command at a DOS prompt (replace the string "purify" with "coverage" or "quantify", depending on the tool you are using):
    purify /java startserver.bat <server name>
    The command line includes startserver.bat (Websphere Application Server startup sequence initialization). Therefore, all rules that apply to the startserver.bat command are enforced. You should set the Websphere Application Server bin directory (e.g. C:\Program Files\Websphere\AppServer\bin) or your profile directory as the current directory and use the existing server name. You can also use other commands and environment variables accepted by startserver.bat. In order for PurifyPlus profiling to work properly, you should ensure that your Websphere Application Server startup sequence doesn’t engage other JVMPI related agents, as they may interfere with the PurifyPlus agent.
    There are additional PurifyPlus command line options you may choose to use in your profiling session:
    -save-data=<profile name>
    This option will start the PurifyPlus server without the GUI and save the data to a file that is viewable in the PurifyPlus GUI. \
    save-data=<profile name>%d
    This is a slight variation on the previous option. It creates numbered versions of the data file instead of overwriting any existing files.
  • Modify the system environment to enable JVMPI
    This option works well in situations where you can’t use the command line. For example, enabling profiling of a JVM hosted by a system service.
    The disadvantage is that specifying the environment settings in the SYSTEM environment causes all Java processes that start on your system to run with the profiler attached.
    The Java Virtual Machine recognizes an environment variable for adding options that were not specified on the command line. The name of this variable is vendor specific. The IBM JVM, which is commonly used with Websphere Application Server, uses IBM_JAVA_OPTIONS. The Sun JVM uses _JAVA_OPTIONS. You can set the appropriate variable in the environment hosting the Websphere Application Server JVM. These are the values to be set:
    -XrunPureJVMPI:<Profiling Type>
    <Profiling Type> is either purify, quantify, or coverage, depending upon the tool being used.
    You also need to set the system environment variable PPLUS_HOME to point to your PurifyPlus installation folder (C:\Program Files\Rational\PurifyPlus, by default).
    If you start the Websphere Application Server server using the Startserver.bat script, you may set these variables in the user environment or in the environment of the command shell where you start the script. If you want to apply these settings for a Websphere Application Server server running as a system service, you have to add these variables to the system environment and reboot your system. Please note, if you set these variables in the system environment, any Java process started on your system will be running with the profiler attached. If you are planning to run JVMs other than the one hosting Websphere Application Server, consider changing the Websphere Application Server configuration file, as described below.
  • Modify the Java command line options in the Websphere Application Server server configuration file
    This method is preferred when you target a specific server on a specific Websphere Application Server node. The best way to apply configuration changes is to use the Websphere Application Server administrative console. It is possible to edit the server configuration file directly, however, if the configuration was cached, these changes may not apply until you restart all active Websphere Application Server nodes.
    When the Java process for hosting Websphere Application Server is initialized, it gets its command line options from the server configuration file. This file exists for every Websphere Application Server node and every Websphere Application Server server. The location and name of this file is:
    <WAS root>\profiles\<your active profile>\config\cells\< cell id>\nodes\<node id>\servers\<server name>\server.xml
    For example, if Websphere Application Server is installed in C:\WAS, the profile name is ‘MyProfile’, the cell id is ‘MyCellId’, the node id is ‘MyNodeId’, and the server name is ‘MyServer’. The configuration file path would be C:\WAS\profiles\MyProfile\config\cells\MyCellId\nodes\MyNodeId\servers\MyServer\server.xml.
    The best way to change the profile is to use the Websphere Application Server administrative console. However, if you do not have access to the console or do not have sufficient rights to edit the server configuration, you may edit the XML file directly. You should locate the jvmEntries element in this file and change the appropriate VM options by adding the JVMPI loading option: -XrunPureJVMPI:<Profiling Type>, where <Profiling Type> is replaced by purify, quantify, or coverage, depending on the tool being used. For example:
    <jvmEntries xmi:id="JavaVirtualMachine_1115850454007" verboseModeClass="false" verboseModeGarbageCollection="false" verboseModeJNI="false" runHProf="false" hprofArguments="" debugMode="false" debugArgs="-Djava.compiler=NONE -Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7777" genericJvmArguments="-DPD_DT_ENABLED=true -XrunPureJVMPI:Purify" />
    After saving the file or applying these changes from the administrative console, you should restart the server process. After the new instance of Websphere Application Server starts, it will run with the appropriate profiler attached.
    To enable PurifyPlus profiling in the Websphere Application Server administrative console, you should log in as administrator and navigate to the following location:
    Application servers >[ server name] > Process Definition > Process Execution > Java Virtual Machine
    In the ‘Generic JVM Arguments’ box add the following string (with the appropriate profiling type):
    –XrunPureJVMPI:<Profiling Type>
    If you want to take advantage of line level profiling, you will have to add the following line to the configuration file:
    Of course, the PPLUS_HOME environment variable should be properly defined to point to your PurifyPlus installation directory.

Specific notes for Websphere Application Server running as a system service

    There are two things you need to keep in mind about system services:
    1. They usually do not have a UI enabled console, also known as a WinStation.
    2. They run in a security context different from the registered user, usually in the “NT AUTHORITY\SYSTEM” context.

    If you enable profiling for a service, it will try to create a PurifyPlus Server process as soon as the JVMPI agent gets loaded. If you do not change the default settings, this process will inherit the ‘headless’ console and the service security context. This may stop PurifyPlus from initializing properly.
    The easiest workaround is to start an instance of the PurifyPlus server (the GUI) before you enable profiling and restart the Websphere Application Server hosting service. If the JVMPI agent detects a running instance of the PurifyPlus Server, it won’t create a new one, but will instead open a communication channel with the existing server.
    If you start the PurifyPlus server from a remote terminal session and plan to attach it to a system service, you should also set the following environment variable in the SYSTEM environment:
    By default, processes started from remote terminal sessions create system objects in the remote session specific namespace. At the same time, the PurifyPlus JVMPI agent loaded into the service creates system objects in the ‘BaseNamedObjects’ namespace. This makes the existing PurifyPlus server invisible to the JVMPI agent. The environment variable above helps to overcome this problem by instructing both the agent and the PurifyPlus Server process to create named objects in the ‘Global’ namespace.

Reducing memory and performance overhead

    Using prefilters to reduce the number of classes profiled

    Each class and each method monitored by PurifyPlus allocates a certain amount of memory for internal structures. The size of this memory varies for different types of profiling. Coverage takes the least amount of memory, while Purify takes the most. J2EE applications running on Websphere Application Server tend to load tens of thousands of classes and create a very large number of objects. To limit the number of traceable objects, PurifyPlus offers the ability to prefilter unnecessary classes. The prefiltering dialog is found on the “PowerCheck” tab, which can be reached from the main menu via Settings -> Default Settings or Settings -> Executable Settings. On the PowerCheck tab, click the Configure button in the Java/Managed section. This will open the Class Instrumentation dialog.
    The fewer classes you monitor, the more memory you save. If you know exactly which classes to monitor, you should use the Selected Classes option to add patterns that match the package names for the classes you want to monitor. You may use regular expressions (e.g. use the * character as a wild card) when creating patterns.
    If you are not sure which classes to monitor, it is recommended to start with the predefined prefilters in the All Classes list. This will exclude most of the system and Websphere Application Server internal classes, leaving more space for user-defined code.
    If you use Purify to monitor Java memory, you should set the Purify option -memprof-track-filtered-method-objects=OFF. This will reduce the amount of memory allocated for monitoring the garbage collected heap. When this option is set to ON (which is the default), Purify will monitor all allocated objects, even those allocated by the prefiltered classes.
    Another way to reduce PurifyPlus memory overhead is to run in Function mode. In this mode you won’t have access to annotated source but you will still have access to the same profiling data you do in Line mode. It is possible to switch back to Line mode after you have determined any additional sets of classes to filter. Once this is done, you will have more memory available for tracking line level information. To switch between Line and Function mode use the PowerCheck tab of the Default Settings or Executable Settings dialog.

Limit memory space allocated by the JVM

    The JVM does not typically run the garbage collector as long as there is available memory. This allows large Java applications to take over the entire user space. To set the limit and leave some space for native code, the JVM has a special option: -Xmx <max heap size>. For example: –Xmx 256m sets the upper JVM heap limit to 256 MB. Once this limit is reached, the garbage collector will have to clear some space before the JVM can allocate new objects. Since PurifyPlus is using native code memory for allocating its internal structures, it makes sense to shift the Java heap limit down if you want to track a larger number of objects. This may make the garbage collector work harder and therefore consume more time, but it will provide extra space for PurifyPlus and let you monitor more data. If Purify gives you memory allocation warnings or dataset processing errors, try to adjust the –Xmx option to move the upper memory limit down.

Save and close snapshots

    Each snapshot or finished application run displayed in the navigation pane represents one dataset. A certain amount of memory is allocated for each open dataset. Some datasets may use 200 MB of heap memory or more. Therefore, leaving too many open snapshots creates an unnecessary memory load. To conserve memory, save and close snapshots. You can open them later when active, profiled applications are not running.

WAS Profiling With PurifyPlus.pdf

Cross Reference information
Segment Product Component Platform Version Edition
Software Development Rational PureCoverage Runtime Windows 7.0
Software Development Rational Purify Runtime Windows 7.0
Software Development Rational Quantify Runtime Windows 7.0

Document information

More support for:

Rational PurifyPlus family

Software version:


Operating system(s):


Reference #:


Modified date:


Translate my page

Content navigation