Eclipse Test & Performance Tools (TPTP) project provides an open platform that allows a developer to profile and analyze execution of Java applications. Here, we present the steps needed to enable Java profiling using TPTP and Apogee JREs.

Introduction.

The profiling solution based on TPTP consists of several components, including:
  • Eclipse IDE & TPTP plugins - run on the host system and retrieve profiling data from the target system.  The information is then interpreted and displayed for user review in a graphical format.
  • piAgent - shared library that is loaded as a part of J9 process (on the target system) and interacts directly with the VM using JVMPI (or JVMTI) protocol to collect profiling information.  The information is then sent to an external process (ACServer).
  • Agent Controller (ACServer) - a standalone process that runs on the target system and mediates a flow of information between Eclipse/TPTP and piAgent.

Installation of TPTP.

  • a copy of Eclipse IDE can be obtained free of charge from www.eclipse.org site
  • to download and install TPTP plugins using eclipse menu system,
    • 'Help'->'Install New Software'
    • under 'Work with:', select 'Galileo'
    • select 'Test and Performance'->'Next'
    • follow instruction to complete installation and restart Eclipse

Installation of Agent Controller.

Eclipse project provides ports of AgentController and piAgent for some of the environments.  Target-specific ports of the above can be created in-house or provided by Apogee.  Once the Agent Controller has been placed on the target system, it needs to be configured by editing $TPTP_AC_HOME/config/serviceconfig.xml file to reflect proper locations of both Agent Controller and the VM binaries (on the target system). acsetenv.sh script should also reflect above changes and must be run prior to invocation of Agent Controller. To test proper configuration of Agent Controller:
  • make sure tcp ports 10002 and 10006 are available for use by Agent Controller
  • open terminal window and start Agent Controller
    • % acsetenv.sh
    % ACStart.sh
    Starting Agent Controller.
    ACServer started successfully.
  • open terminal window
    • % acsetenv.sh
    % SampleClient
    Connected to the Agent Controller on "localhost" at port number 10006 The Time Collector Agent ID: 103
    Established a data channel with the agent.
    Sending 5 Hello messages over data channel to TimeCollector ...
    Start the TimeCollector ...
    Incoming data: Hello from Time Collector Agent - Count 0
    ...
    Stop the TimeCollector ...
    Incoming data: Hello from Time Collector Agent - Count 5
    ...
    All finished
    Press any key to exit...
  • stop Agent Controller
    • % ACStop.sh
    Shutting down Agent Controller…
    ACServer stopped

Running JRE with piAgent.

In order to run JRE with piAgent, following steps should be followed:
  • start (if not already running) Agent Controller via ACStart.sh script
  • configure JRE to properly load piAgent shared library:
    % export TPTP_AC_HOME=/opt/apogee/agntctrl
    % export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$TPTP_AC_HOME/lib
  • enable piAgent functionality by enhancing command-line:
    % j9 -XrunpiAgent:server=enabled ...

Profiling Java Applications.

With the JRE running and waiting for connection from the host side, Eclipse/TPTP can be configured to obtain and display profiling information:
  • create a profile configuration
    • 'Run'->'Profile Configurations'->'Attach to Agent'->'New'
    • add a remote target as one of 'Default Hosts' by clicking 'Add...'
  • connect to the remote target
    • select remote target from the list of 'Default Hosts'
    • select 'Agents' tab
    • use 'Refresh' button to view available profiling agents provided by piAgent
    • select only one profiling agent and click 'Profile' to start

Additional Resources.

To get more information about profiling using TPTP and interpreting profiled data, check out:

Known Issues.

TPTP randomly stops collecting data from the piAgent/Agent Controller. This behavior can be mitigated by restricting the number of packages, classes, methods to be profiled via filter usage.