This document provides a simple
solution to profile Java code running with virtually any application server.
In this document:
<OptItDir> is the directory where
OptimizeIt has been installed. (ex: c:\OptimizeIt\OptimizeIt40D)
1) Requirements
-
Java code should be executed with a virtual machine
supported by OptimizeIt. OptimizeIt supports most virtual machines derived
from Sun's virtual machine: JDK 1.1.x, 1.2.x and 1.3.x. OptimizeIt also
supports any virtual machine fully JNI/JVMPI compliant which includes IBM
JDK 1.2.2 and 1.3.
-
The application server starting the virtual machine
should provide a way to set basic Java parameters.
2) How OptimizeIt works
OptimizeIt is divided in 2 parts:
-
the audit system which runs in the virtual machine
of the application server and collects the profiling information
-
the OptimizeIt GUI that attaches to the audit system,
displays the profiling information and interacts with the audit system.
In order to integrate OptimizeIt with your application
server, you need to start the audit system in the virtual machine of your
application server. Once the audit system is started, you can start the
OptimizeIt GUI and attach to the audit system. At that point, you get the
profiling information for your servlets, JSPs and EJBs just by executing
them.
The following chapters explain how to configure
your application server to run with the audit system and how to add the
OptimizeIt servlet to your application server. The OptimizeIt servlet is
a small servlet that conveniently allows you to start the audit system
in the virtual machine of your application server.
3) Changing how the virtual machine is started
Virtual machine startup parameters
In order to start profiling with OptimizeIt, the
following parameters should be set when starting the virtual machine:
-
CLASSPATH should include <OptItDir>\lib\optit.jar
-
PATH should include <OptItDir>\lib
-
Class garbage collection should be disabled: -noclassgc
with JDK 1.1 and -Xnoclassgc with JDK 1.2
-
JIT should be disabled: -Djava.compiler=NONE
-
With JDK 1.2 and JDK 1.3, it is also necessary to
start the JVMPI agent -Xrunoii and to use the classic runtime
-classic
Important note:
the -classic
parameter should always be the first parameter specified to the virtual
machine or it will be ignored and the virtual machine may fail to start.
Note also that with the Sun JDK 1.3.1 the hotspot
runtime can be used for profiling and therefore the -classic option
is not required.
Common ways to set virtual machine startup parameters
These parameters may be set differently depending
on your application server, here are different common ways:
Using application server administration
tool
If your application server provides an administration
tool, start it and try to find how to set java parameters. Then change
them to include OptimizeIt parameters.
Modifying application server property
file
Many application servers use a property file that
contains configuration settings. Try to find this property file. Edit it
and look for the properties dealing with CLASSPATH, PATH and java parameters.
Change them to include OptimizeIt parameters.
Modifying application server launching
script
Different application servers can be started with
a script file, that generally executes the virtual machine to launch the
application server class. In that case, edit the launching script file.
If PATH is not set, append at the beginning of the file the following line:
SET PATH=<OptItDir>\lib;%PATH%
Add also OptimizeIt parameters to the virtual
machine invocation.
Note: in all cases, you are advised to
modify your system CLASSPATH and PATH environment variables to include
the following directories:
CLASSPATH: <OptItDir>\lib\optit.jar
PATH: <OptItDir>\lib
Examples
JDK 1.1:
set PATH=C:\OptimizeIt\lib;%PATH%
set CLASSPATH=C:\OptimizeIt\lib\optit.jar;%CLASSPATH%
java -noclassgc -Djava.compiler=NONE
server.Main
JDK 1.2 or later:
set PATH=C:\OptimizeIt\lib;%PATH%
set CLASSPATH=C:\OptimizeIt\lib\optit.jar;%CLASSPATH%
java -classic -Xrunoii
-Xnoclassgc -Djava.compiler=NONE server.Main
4) Adding OptimizeIt servlet to the Application Server
Copy the OptimizeIt servlet <OptItDir>\lib\servlet\OptimizeIt.class
to the application server servlet directory.
Note about security issue
If you use a 1.2 or more later virtual machine, you may have to give
all permissions to OptimizeIt library for correct execution. You may set
these permissions using the administration tool of your application server
if it provides one, or by modifying the policy file.
Example: Java Web Server 2.0 policy file is modified to execute OptimizeIt
servlet without security exception. The following lines are added to the
policy file:
/* Permissions for OptimizeIt */
grant codeBase "file:<OptItDir>/lib/optit.jar" {
permission java.security.AllPermission;
};
5) Profiling with OptimizeIt servlet
Start OptimizeIt's audit system
-
Restart your application server, for the changes you have made to be effective.
-
Invoke the OptimizeIt servlet from a web browser. The URL depends on your
application server, but should look like: http://localhost/servlet/OptimizeIt
-
In the HTML page that the servlet provides, change the port number if necessary.
-
Select the "Disable memory profiler" option if you only want to focus on
CPU usage.
-
Select "Enable OptimizeIt's audit system API" if your code enables/disables
the profiler by using OptimizeIt's audit system API.
-
Press the "Start OptimizeIt Audit System" button to start the profiler.
Once this operation is done, you should see a message in your web browser
indicating that OptimizeIt's audit system is running.
Attach from OptimizeIt
Now that the application server is running with OptimizeIt profiler,
you can start OptimizeIt and attach to the virtual machine.
-
Start OptimizeIt from the Start menu.
-
Close the Edit Settings panel by pressing the OK button.
-
From the Program menu, select Attach.
-
Change the port number and the hostname if necessary.
-
Press the Attach button.
Note: OptimizeIt does not have a "detach" function. If you press
the stop button in OptimizeIt, the servlet engine exits. After doing this,
you may need to start it again and to invoke the OptimizeIt servlet to
restart the profiler.
6) Starting OptimizeIt profiler from your Java code
While the OptimizeIt servlet is convenient to start profiling quickly,
you may want to automatically start OptimizeIt profiler with one of your
servlet. That way, you don't have to invoke the OptimizeIt servlet to start
the audit system before testing your servlets.
Starting OptimizeIt profiler can be easily done by using OptimizeIt's
API. OptimizeIt's API is documented in OptimizeIt user manual, chapter
9.
The following code demonstrates how to start the profiler from your
servlet:
import intuitive.audit.Audit;
...
static boolean isProfilerStarted = false;
if(!isProfilerStarted) {
/* Start OptimizeIt's
profiler */
Audit.start(1470, Audit.PROFILERS_ALWAYS_ENABLED);
isProfilerStarted = true;
}
...
Note: you will need to add <OptItDir>\lib\optit.jar to your
CLASSPATH to compile this code
Once OptimizeIt's profiler is running, you can start OptimizeIt and
attach to the servlet engine.
Copyright (c) 1997, 1998, 1999, 2000, 2001 Intuitive
Systems Inc. All rights reserved. Specifications subject to change without
notice.
OptimizeIt is a trademark of Intuitive Systems, Inc.
Java and all Java-based trademarks and logos are trademarks
or registered trademarks of Sun Microsystems, Inc. All other brand
names and products are trademarks or registered trademarks
of their respective holders.