Profiling an application in stand-alone mode

The following information applies to Windows.  The following information applies to Linux. You can profile an application in stand-alone mode (that is, from the command line), without having the the Test and Performance Tools Platform installed. However, you do need to have the Agent Controller installed on the machine where the application to be profiled resides.

You can profile an application in stand-alone mode by invoking the Java Profiling Agent, which is a library that attaches to a Java virtual machine (JVM) to capture and record the behavior of your Java application. The output from the agent is in the form of XML fragments.

** Note: Before starting the command line invocation, make sure that the profiling agent libraries are setup in the system LD_LIBRARY_PATH variable for TPTP 4.5.2 (or lower). For TPTP 4.6.0 (or higher) which do not support Java 1.4 (or lower), PATH(Windows)/LD_LIBRARY_PATH(Linux) setting is optional and the details will be described later. Read thru the following section for instruction on environment variable setup.

If need PATH(Windows)/LD_LIBRARY_PATH(Linux) setting, how to setup Environment variables?

Before starting the Java process, please make sure %JAVA_HOME%\bin has been added into PATH and then setup the following variables in the same Command Prompt session:

For Windows:

  • Set TPTP_AC_HOME=<<Agent Controller Home>>
  • Set JAVA_PROFILER_HOME=%TPTP_AC_HOME%\plugins\org.eclipse.tptp.javaprofiler
  • Set PATH=%JAVA_PROFILER_HOME%;%TPTP_AC_HOME%\bin;%PATH%

  • For Linux:

  • export TPTP_AC_HOME=<<Agent Controller Home>>
  • export JAVA_PROFILER_HOME=$TPTP_AC_HOME/plugins/org.eclipse.tptp.javaprofiler
  • export LD_LIBRARY_PATH=$JAVA_PROFILER_HOME:$TPTP_AC_HOME/lib:$LD_LIBRARY_PATH


    **Note: Actually, it is possible not to use environment variables JAVA_PROFILER_HOME and TPTP_AC_HOME for TPTP 4.6.0 (or higher). The dependency on JAVA_PROFILER_HOME and TPTP_AC_HOME have been removed. So you can add the necessary path directly into:

    PATH for Windows:

  • <<Agent Controller Home>>\plugins\org.eclipse.tptp.javaprofiler:<<Agent Controller Home>>\bin


  • LD_LIBRARY_PATH for Linux:
  • <<Agent Controller Home>>/plugins/org.eclipse.tptp.javaprofiler:<<Agent Controller Home>>/lib


  • Using the profiler with Java 1.4 (or lower) virtual machines
    Using the profiler with Java 5.0 (or higher) virtual machines
         Using environmental variables setting and the -agentlib Java option to invoke the Java Profiling Agent
         Only using the -agentpath Java option to invoke the Java Profiling Agent
    Format of the Class Filter file
    Controlling the Java Profiling Agent
    Notes

    Using the profiler with Java 1.4 (or lower) virtual machines

    Use the -Xrun Java option to invoke the Java Profiling Agent:

        -XrunpiAgent:agent_parm[,agent_parm]*

    For example, to profile PerformanceExample.java, using filters that are defined in the file myFilters.txt, and directing the data from the profiling session to a file called PEProfilingData, you would type the following on a command line:
        java -XrunpiAgent:server=standalone,filters=myFilters.txt,file=PEProfilingData.trcxml PerformanceExample

    Note: If you want to start WebSphere Application Server Version 6 (WAS) in profiling mode from the command line, you have to perform the following steps:

    1. Go to <profile root>/config/cells/<nodename>Cell/nodes/<nodename>/servers/server1
    2. Edit the jvmEntries element in the server.xml file. In that element, there is an attribute called genericJvmArguments. Append -XrunpiAgent:server=enabled to the attribute value.
    3. Restart WAS.
       

    By augmenting the -XrunpiAgent parameter you can specify several different modes to run the profiling agent in. The parameter agent_parm can take one of the following values:

    Using the profiler with Java 5.0 (or higher) virtual machines

    Using environmental variables setting and the -agentlib Java option to invoke the Java Profiling Agent

    To run the Java Profiling Agent on Linux with -agentlib option, perform the LD_LIBRARY_PATH setting steps mentioned before, then execute the Java application with the -agentlib parameter as described above.


    Use the -agentlib Java option to invoke the Java Profiling Agent:

    -agentlib:JPIBootLoader=JPIAgent[:[help]|[<option>=<value>,...]];<profiler>[:<option>=<value>,...]

    The command line is structured as follows:

    JPIBootLoader
    is the library that loads the profiling agent.
    JPIAgent
    is the Java 5.0+ profiling agent. By augmenting the JPIAgent part of the command line with additional options, you can control the behavior of the profiling agent. The following options are supported:
    <Profiler>
    is the name of the Profiler Library to load. Some of the available profilers support additional profiler-specific options, as described below:

      To run the Java Profiling Agent in standalone mode, perform the following steps:

    1. Setup environmental variables as mentioned before
    2. Execute the Java application with the -agentlib parameter as described above

    Note:
    On Linux, make sure to surround the entire -agentlib argument with single quotes. Otherwise, the Linux shell may interpret the semicolon (;) preceding the profiler name as a command terminator and the Java application will not be executed.

    Examples

    1. To profile the "HelloWorld" Java application with the CPU Profiler in standalone mode and write the results into log.trcxml:


      For Windows:

      java -agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf HelloWorld


      For Linux:

      java '-agentlib:JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf' HelloWorld


    2. To profile the "HelloWorld" Java application with the Heap Profiler in standalone mode, use the filters defined in myFilter.txt, and collect information about the source locations where objects are allocated:


      For Windows:

      java -agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true HelloWorld


      For Linux:

      java '-agentlib:JPIBootLoader=JPIAgent:server=standalone,filters=myFilter.txt;HeapProf:allocsites=true' HelloWorld


    Only using the -agentpath Java option to invoke the Java Profiling Agent

    For TPTP 4.6.0 (or higher), it is possible to not set additional environmental variables. The answer is to use -agentpath instead of PATH(Windows) / LD_LIBRARY_PATH(Linux) setting + -agentlib Java option. It is suggested -agentpath is only used when you can not set environmental variables for some reason. Compared with -agentlib command line, there are two differences. Other profiling options are the same with -agentlib part.


      The first difference is JPIBootLoader part changes in command. You should give the profilers' absolute path before JPIBootLoader. And please note on Linux, when using absolute path and file name to load a library, the entire library file name must be used. So libJPIBootLoader.so should be used instead of JPIBootLoader or libJPIBootLoader for Linux.


      The second difference is related with profiling -server option. We have known there are three possible values for -server option: standalone, enabled and controlled mode. For standalone mode, it is enough to provide with profilers' absolute path after -agentpath as mentioned above. However, Agent Controller will be needed for enabled and controlled. Since Agent Controller path information is not set in environmental variables, it must be provided in command line as need: when you are using -agentpath, if profilers are Eclipse default plugins or Agent Controller self-contained Java profilers, additional Agent Controller path information is unnecessary, otherwise you should provide it with profiling option ac_home in -agentpath command line. Please refer to examples below about details.


    **Note about Eclipse default plugins or Agent Controller self-contained Java profilers:


    For Windows:

  • Eclipse default plugins Java profilers should be in:
    <<Eclipse Home>>\plugins\org.eclipse.tptp.platform.jvmti.runtime_<version>\agent_files\<os_platform>
  • Agent Controller self-contained Java profilers should be in:
    <<Agent Controller Home>>\plugins\org.eclipse.tptp.javaprofiler

  • For Linux:

  • Eclipse default plugins Java profilers should be in:
    <<Eclipse Home>>/plugins/org.eclipse.tptp.platform.jvmti.runtime_<version>/agent_files/<os_platform>
  • Agent Controller self-contained Java profilers should be in:
    <<Agent Controller Home>>/plugins/org.eclipse.tptp.javaprofiler
  • Examples

    1. To profile the "HelloWorld" Java application with the CPU Profiler in standalone mode and write the results into log.trcxml:


      For Windows:

      java -agentpath:<Java profilers absolute path>\JPIBootLoader=JPIAgent:server=standalone,file=log.trcxml;CGProf HelloWorld


      For Linux:

      java '-agentpath:<Java profilers absolute path>/libJPIBootLoader.so=JPIAgent:server=standalone,file=log.trcxml;CGProf' HelloWorld


    2. To profile the "HelloWorld" Java application with the CPU Profiler in enabled mode and write the results into log.trcxml using Agent Controller self-contained Java profilers:


      For Windows:

      java -agentpath:<AC self-contained Java profilers absolute path>\JPIBootLoader=JPIAgent:server=enabled,file=log.trcxml;CGProf HelloWorld


      For Linux:

      java '-agentpath:<AC self-contained Java profilers absolute path>/libJPIBootLoader.so=JPIAgent:server=enabled,file=log.trcxml;CGProf' HelloWorld


    3. To profile the "HelloWorld" Java application with the CPU Profiler in enabled mode and write the results into log.trcxml when Agent Controller path info is needed:


      For Windows:

      java -agentpath:<Java profilers absolute path>\JPIBootLoader=JPIAgent:ac_home=<Agent Controller Home>,server=enabled,file=log.trcxml;CGProf HelloWorld


      For Linux:

      java '-agentpath:<Java profilers absolute path>/libJPIBootLoader.so=JPIAgent:ac_home=<Agent Controller Home>,server=enabled,file=log.trcxml;CGProf' HelloWorld


    Format of the Class Filter file

    The filter file should specify three fields, package/class, method, and mode in the following format:
       package/class method mode

    where:

    package/class
    This field is used to specify a pattern for a package or a class name. The pattern should be specified as a string with no embedded blanks. The string may contain a single asterisk (*) either at the beginning of the string or trailing the string, e.g. *.mypackage or org.mycompany.*. The * matches zero or more characters, thus making the pattern a generic prefix or suffix pattern. A sole * can also be specified to represent all strings.
    method
    This field is used to specify a pattern for the method name. The pattern should be specified as a string with no embedded blanks and with the same specification rules as the class field.
    mode
    This field specifies whether the package or class that matches the pattern is to be included or excluded from profiling. The value for mode is either INCLUDE or EXCLUDE.

    Filter patterns are processed in the order that they are specified until the first pattern match succeeds. If the class name does not match any of the specified filter patterns, the default is to INCLUDE the class.

    Controlling the Java Profiling Agent

    When the Java Profiling Agent is started with the server=enabled or server=controlled parameter, communication with the agent is done using the client workbench by means of the Agent Controller on the host machine.

    Notes

     

    Related concepts
    Overview of the Profiling Tool
    Profiling resources

    Related tasks
    Launching or attaching a Java process
    Using the Profiling monitor view