Profiling J2SE 5.0 based applications using Eclipse TPTP
Profiling J2SE 5.0 based applications using Eclipse TPTP
The following document explains how the features of JVM 5.0 can be leveraged in TPTP to profile J2SE applications. The new profilining feature in TPTP uses JVMTI to collect and report statistics using the same look and feel as the JVMPI agent.
Table of Contents:
1.0 Introduction - Description and Purpose
2.0 Installing the JVMTI Feature
2.1 Pre-Requisites
2.2 Eclipse Client
2.3 New Java Profiler Runtime
2.4 Configuring the Eclipse Client
3.0 Profiling an Application
3.1 Java Application
3.2 External Java Application
3.3 New Java Profiler runtime execution modes
4.0 Limitations
4.1 Feedback

1.0 Introduction - Description and Purpose

The Eclipse Test & Performance Tools Platform (TPTP) New Java Profiler can be used to profile Eclipse plug-ins, local Java applications or complex applications running on multiple hosts and different platforms. The New Java Profiler is designed to work with Java applications based on Java 2 Standard Edition 5.0 (Java 1.5) and beyond.

The New Java Profiler is based on the Java Virtual Machine Tool Interface (JVMTI) introduced in J2SE 5.0, which replaces the earlier experimental Java Virtual Machine Profiler Interface (JVMPI). The Profiler uses a substantially different philosophy from the current TPTP JVMPI-based Profiler. Instead of relying on VM-generated events for monitoring application behavior (such as method entry and exit events, object allocations and so on) it uses Byte Code Instrumentation (BCI) to inject small pieces of code which tracks the application execution. This technique allows for efficient monitoring of specific parts of the application, without imposing a noticeable overhead on other parts of the application which are not being monitored.

This technology preview release of the New Java Profiler includes an Execution Time Analysis Data Collector. Heap and Thread Information Collectors are scheduled for the TPTP 4.3 Release.


2.0 Installing the JVMTI Feature

The JVMTI features in TPTP is offered as a technology preview item. The following sections describe how the features can be downloaded and setup to successfully start a profiling session.


2.1 Pre-Requisites

Java: The New Java Profiler requires J2SE 5.0 (Java 1.5) or higher.

Eclipse TPTP Data Collection Engine: The New Java Profiler runtime depends on the TPTP New Technology Agent Controller version 4.2+. Download the New Technology Agent Controller and follow the directions in the “Getting Started” guide to install the Agent Controller. The Agent Controller is available under the “New Technology Agent Controller” section of the TPTP 4.2 Download page.

TPTP Eclipse Runtime: The New Java Profiler Eclipse client depends on the TPTP Eclipse Runtime version 4.2+. Download the TPTP Eclipse Runtime and extract the plugins to your <Eclipse install-home> directory.


2.2 Eclipse Client

Download the New Java Profiler client (JVMTI client) and extract the plugins to your <Eclipse install-home> directory. The JVMTI Client is available under the "New Java Profiler" section of the TPTP 4.2 Download page.


2.3 New Java Profiler Runtime

Download the New Java Profiler runtime and extract the files to the <New Technology Agent Controller install-home> directory. The runtime files are extracted to the plugins directory of the New Technology Agent Controller. Make sure you download the runtime version that matches your target platform. The New Java Profiler is available under the “New Java Profiler” section of the TPTP 4.2 Download page.


2.4 Configuring the Eclipse Client

The New Java Profiler works with the New Technology Agent Controller. The client should be configured to connect to the New Technology Agent Controller port. This is configured in the file "serviceConfig.xml" in the <New Technology Agent Controller install-home>/config directory. The default client connection port number of the New Technology Agent Controller is 10006.

To configure the hostname, navigate to the Preferences menu ( Window > Preferences ) in the Eclipse Workbench and click on "Profiling and Logging". Change the "Agent Controller local port" to 10006. You will also need to select "Host" under "Profiling and Logging" to add a localhost entry with port 10006 (see figure 2.1).


Figure 2.1 - Preference page


3.0 Profiling an Application

The JVMTI data collector is associated with all launch items that appear under the profile launch configuration. The sections below describe how the user can profile a Java application that resides inside/outside the Eclipse workbench.


3.1 Java Application

To profile a Java application that resides in your workbench, select "Profile" from the Profile drop down menu (see figure 3.1). This opens the profile launch configuration.


Figure 3.1 - Profile drop down menu

Create a new launch item of type "Java Application" > Use the main tab to select a project and a main class > Select the "Monitor" tab as shown in figure 3.2. Click on the "Java Profiling with Instrumentation" data collector. Click on Edit options to set any desired filter > Select "Execution Time Anlysis" under "Java Profiling with Instrumentation" and select "Edit Options" > Select the option "Show Execution Flow Graphical Details". Click on the Profile button to launch the application in Profile mode.


Figure 3.2 - The profile launch configuration

Following the successful launch of the application you will see the process and the agent appear under the "Profiling Monitor" view.

Views

The TPTP profiling tool allows you to interact with your profiled application. You can pause and resume monitoring, collect execution statistics and execution flow or terminate the application. The Profiling and Logging perspective provides context specific views for analyzing your application. Right click the agent that appears under the Profiling Monitor view to get a listing of the available views (see figure 3.3).


Figure 3.3 - Available views


3.2 External Java Application

The external Java application launch item enables users to select a Java executable that resides outside the Eclipse workbench. An additional tab you will notice under the External Java application launch item is the Host tab, which allows users to select the host under which the application resides in. To launch an external application locally, select localhost:10006 (created earlier in section 2.4). Use the main tab as shown in figure 3.4 to select the location of the external main class. Use the same settings as described in section 3.1 under the "Monitor" tab and click on "Profile" to start the profiling session.


Figure 3.4 - Profile launch configuration


3.3 New Java Profiler runtime execution modes

The New Java Profiler runtime can be executed in three different modes as described below:

Mode Description Instructions
Standalone

The new Java Profiler can be used as a standalone application to collect profiling data info a file. The data emitted by the Profiler complies with the XML4Profiling Java Trace format Specification. The output file can be imported to the Eclipse workbench using the import profiling file option available in TPTP.

To run the new Java Profiler in standalone mode on Windows:

a) Set TPTP_AC_HOME=<<Agent Controller Home>>

b) Set JAVA_PROFILER_HOME=%TPTP_AC_HOME%\plugins\org.eclipse.tptp.javaprofiler

c) Set PATH=%JAVA_PROFILER_HOME%;%PATH%;%TPTP_AC_HOME%\bin

d) Set PATH=%PATH%;%JAVA_HOME%\bin

e) Execute the following command:

   java -agentlib:JPIBootLoader=JPIAgent:server=standalone;CGProf <<Your Application to profile>>

 To run the new Java Profiler in standalone mode on Linux:

a) Set TPTP_AC_HOME=<<Agent Controller Home>>

b) Set JAVA_PROFILER_HOME=%TPTP_AC_HOME%/plugins/org.eclipse.tptp.javaprofiler

c) Add the following directories to LD_LIBRARY_PATH:

   %JAVA_PROFILER_HOME%:%TPTP_AC_HOME%/lib

d) Execute the following command:

   java ‘-agentlib:JPIBootLoader=JPIAgent:server=standalone;CGProf’ <<Your Application to profile>>

 The profiling output will be written to a file named trace.trcxml in the current directory.

NOTE: On Linux, make sure to surround the entire

–agentlib argument with single quotes (as shown above). Otherwise, the Linux shell may interpret the ; preceding CGProf as a command terminator and the Java application will not be executed.

Enabled The New Java Profiler is executed from the command line without suspending the Java process. The user can start the profiling session by attaching to the profiling agent using the TPTP workbench. Repeat the steps for running the profiler in standalone mode but use the following command to launch the process: "java.exe -agentlib:JPIBootLoader=JPIAgent:server=enabled;CGProf <<Your Application to profile>>"
Controlled The New Java Profiler is executed from the command line and suspends the Java process until a client attaches to the profiling agent. This mode is used by the Eclipse Client to launch the an Application under the profiler. Repeat the steps for running the profiler in standalone mode but use the following command to launch the process: "java.exe -agentlib:JPIBootLoader=JPIAgent:server=controlled;CGProf <<Your Application to profile>>"

NOTE: Agent discovery functionality is not yet available in TPTP 4.2. Thus, both “enabled” and “controlled” modes cannot be used in this release. The user interface for discovering agents will be available in the early iterations of TPTP 4.3.


4.0 Limitations


4.1 Feedback

Please provide feedback by creating bug requests or posting your questions on the TPTP newsgroup