Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Developer's Guide |
Chapter 5
Debugging J2EE ApplicationsThis chapter gives guidelines for debugging applications in Sun Java System Application Server 7. It includes the following sections:
Debugging applications requires that you edit the server.xml file as described in this chapter. For more general information about this file, see the Sun Java System Application Server Administrator’s Configuration File Reference.
Enabling DebuggingWhen you enable debugging, you enable both local and remote debugging.
You can enable debugging in one of these ways:
Sun Java System Application Server debugging is based on the JPDA (Java Platform Debugger Architecture). For more information, see JPDA Options.
Using the Administration Interface
To enable debugging:
- Go to the server instance page.
- Select the General tab.
- Check the Start in Debug Mode box.
- Select the Apply Changes button.
- Restart the server.
- Select the JVM Settings tab and the General option.
- Look in the Debug Options field for address=port_number, and write down this port number. You will need this port number when you attach a debugger.
- If you wish to add JPDA options, follow these additional, optional steps:
- Add any desired JPDA debugging options in Debug Options. See JPDA Options.
- Select the Save button.
Editing the server.xml File
To enable debugging, set the following attributes of the java-config element in the server.xml file:
- Set debug-enabled="true" to turn on debugging.
- Add any desired JPDA debugging options in the debug-options attribute. See JPDA Options.
- To specify the port to use when attaching the JVM to a debugger, specify address=port_number in the debug-options attribute.
For details about the server.xml file, see the Sun Java System Application Server Administrator’s Configuration File Reference.
JPDA OptionsThe default JPDA options in Sun Java System Application Server are as follows:
-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n
If you substitute suspend=y, the JVM starts in suspended mode and stays suspended until a debugger attaches to it. This is helpful if you want to start debugging as soon as the JVM starts.
To specify the port to use when attaching the JVM to a debugger, specify address=port_number.
You can include additional options. A list of JPDA debugging options is available here:
http://java.sun.com/products/jpda/doc/conninv.html#Invocation
Using Sun ONE Studio for DebuggingTo use the Sun ONE Studio 5 debugger with Sun Java System Application Server:
- Start Sun ONE Studio, and mount the directory that contains the application source code you want to debug.
- Select the Runtime tab, then navigate to the Sun Java System Application Server instance that you want to start in debug mode (local or remote).
- Right click on the server instance and select Status from the menu that appears. The Status window appears.
- If the server instance is not running in debug mode, select Stop Server Instance, then select Start in Debug Mode.
- When the server instance is running in debug mode, a port_number is displayed in the Status window and on the status line. Write down this port number.
- Select the Debug menu and the Attach... option.
- Change the Connector:text field to SocketAttach.
- Type the host name of the Application Server in the Host text box.
- Type the port_number in the Port text box, then select OK.
You should be able to debug your Java classes now using Sun ONE Studio.
For help on debugging applications with Sun ONE Studio, select Help, select Contents, then select Debugging Java Programs. You can also consult the Sun ONE Studio 5, Enterprise Edition Tutorial.
Debugging JSPsWhen you use Sun ONE Studio 5 to debug JSPs, you can set breakpoints in either the JSP code or the generated servlet code, and you can switch between them and see the same breakpoints in both.
To set up debugging in Sun ONE Studio, see the previous section. For further details, see the Sun ONE Studio 5, Enterprise Edition Tutorial.
Generating a Stack Trace for DebuggingYou can generate a Java stack trace for debugging as described here:
http://developer.java.sun.com/developer/technicalArticles/Programming/Stacktrace/
If the -Xrs flag is set (for reduced signal usage) in the server.xml file (under <jvm-options>), comment it out before generating the stack trace. If the -Xrs flag is used, the server may simply dump core and restart when you send the signal to generate the trace.
The stack trace goes to the system log file or to stderr based on the log-service attributes in server.xml.
For more about the server.xml file, see the Sun Java System Application Server Administrator’s Configuration File Reference.
Sun Java System Message Queue DebuggingSun Java System Message Queue has a broker logger, which can be useful for debugging JMS, including message-driven bean, applications. You can adjust the logger’s verbosity, and you can send the logger output to the broker’s console using the broker’s -tty option. For more information, see the Sun Java System Message Queue Administrator’s Guide.
LoggingYou can use the Sun Java System Application Server’s log files to help debug your applications. For general information about logging, see the Sun Java System Application Server Administrator’s Guide. For information about configuring logging in the server.xml file, see the Sun Java System Application Server Administrator’s Configuration File Reference.
You can change logging settings in one of these ways:
Using the Administration Interface
To change logging settings:
Editing the server.xml File
To change logging settings, set the attributes of the log-service element in the server.xml file.
You can send exceptions to the client in addition to the log file. Set the following parameter in server.xml. If the client is a browser, exceptions are displayed in the browser.
<log-service ... echo-log-messages-to-stderr=true ... />
For details about the server.xml file, see the Sun Java System Application Server Administrator’s Configuration File Reference.
ProfilingYou can use a profiler to perform remote profiling on the Sun Java System Application Server to discover bottlenecks in server-side performance. This section describes how to configure these profilers for use with Sun Java System Application Server:
The HPROF Profiler
HPROF is a simple profiler agent shipped with the Java 2 SDK. It is a dynamically linked library that interacts with the JVMPI and writes out profiling information either to a file or to a socket in ASCII or binary format. This information can be further processed by a profiler front-end tool such as HAT.
HPROF can present CPU usage, heap allocation statistics, and monitor contention profiles. In addition, it can also report complete heap dumps and states of all the monitors and threads in the Java virtual machine. For more details on the HPROF profiler, see the JDK documentation at:
http://java.sun.com/j2se/1.4/docs/guide/jvmpi/jvmpi.html#hprof
Once HPROF is installed using the following instructions, its libraries are loaded into the server process.
To use HPROF profiling on UNIX, follow these steps:
- Configure Sun Java System Application Server in one of these ways:
- Go to the server instance page in the Administration interface, select the JVM Settings tab, select the Profiler option, and edit the following fields before selecting Save:
- Edit the server.xml file as appropriate:
<!-- hprof options -->
<profiler name="hprof" enabled="true">
<jvm-options>
-Xrunhprof:file=log.txt,options
</jvm-options>
</profiler>
Here is an example of options you can use:
-Xrunhprof:file=log.txt,thread=y,depth=3
The file option is important because it determines where the stack dump is written in Step 6.
The syntax of HPROF options is as follows:
-Xrunhprof[:help]|[:option=value,option2=value2, ...]
Using help lists options that can be passed to HPROF. The output is as follows:
Hprof usage: -Xrunhprof[:help]|[:<option>=<value>, ...]
Option Name and Value Description Default
--------------------- ----------- -------
heap=dump|sites|all heap profiling all
cpu=samples|old CPU usage off
format=a|b ascii or binary output a
file=<file> write data to file java.hprof
(.txt for ascii)
net=<host>:<port> send data over a socket write to file
depth=<size> stack trace depth 4
cutoff=<value> output cutoff point 0.0001
lineno=y|n line number in traces? y
thread=y|n thread in traces? n
doe=y|n dump on exit? y
- You must also change a line in the Sun Java System Application Server start script. The start script file is instance_dir/startserv. Change the following line:
PRODUCT_BIN=appservd-wdog
to this:
PRODUCT_BIN=appservd
- Start the server by running the start script. Since the server runs in the foreground (the change in step 2), the command prompt returns only after the server has been stopped.
- In another window or terminal, find the process ID of the server process.
% ps -ef | grep appservd
This command lists two appservd processes. Look at the PPID (parent process ID) column and identify which of the two processes is the parent process and which is the child process. Note the PID (process ID) of the child process ID.
- Send a SIGQUIT signal (signal 3) to the child process:
% kill -QUIT child_PID
- To stop the Application Server, run the stop script from another window.
% ./stopserv
This writes an HPROF stack dump to the file you specified using the file HPROF option in Step 1. For general information about using a stack dump, see Generating a Stack Trace for Debugging.
- Undo the changes in steps 1 and 2 to return your Application Server to its original configuration.
The Optimizeit Profiler
You can purchase Optimizeit 4.2 from Intuitive Systems at:
http://www.optimizeit.com/index.html
Once Optimizeit is installed using the following instructions, its libraries are loaded into the server process.
To enable remote profiling with Optimizeit, do one of the following:
- Go to the server instance page in the Administration interface, select the JVM Settings tab, select the Profiler option, and edit the following fields before selecting Save:
- Edit the server.xml file as appropriate:
<!-- Optimizeit options -->
<profiler name="optimizeit" classpath="Optimizeit_dir/lib/optit.jar"
native-library-path="Optimizeit_dir/lib" enabled="true">
<jvm-options>
-DOPTIT_HOME=Optimizeit_dir -Xboundthreads -Xrunoii
-Xbootclasspath/a:Optimizeit_dir/lib/oibcp.jar
</jvm-options>
</profiler>In addition, you may have to set the following in your server.policy file:
grant codeBase "file:Optimizeit_dir/lib/optit.jar" {
permission java.security.AllPermission;
};For more information about the server.policy file, see “The server.policy File” on page 57.
When the server starts up with this configuration, you can attach the profiler. For further details, see the Optimizeit documentation.
Note
If any of the configuration options are missing or incorrect, the profiler may experience problems that affect the performance of the Sun Java System Application Server.
The Wily Introscope Profiler
Information about Introscope® from Wily Technology is available at:
http://www.wilytech.com/solutions_introscope.html
Once Introscope is installed using the following instructions, its libraries are loaded into the server process.
To enable remote profiling with Introscope edit the server.xml file as appropriate:
<!-- Introscope options. For Win2K, use ; in classpath -->
<java-config ... bytecode-preprocessors" value="S1ASAutoProbe" ... >
<profiler name="wily" enabled="true"
classpath="Wily_dir/ProbeBuilder.jar:Wily_dir/Agent.jar" >
</profiler>
</java-config>When the server starts up with this configuration, you can attach the profiler. For further details, see the Introscope documentation.
Note
If any of the configuration options are missing or incorrect, the profiler may experience problems that affect the performance of the Sun Java System Application Server.
The JProbe Profiler
Information about JProbe from Sitraka is available at:
http://www.klgroup.com/software/jprobe/
Once JProbe is installed using the following instructions, its libraries are loaded into the server process.
To enable remote profiling with JProbe:
- Install JProbe 3.0.1.1. This version supports JDK 1.4. For details, see the JProbe documentation.
- Configure Sun Java System Application Server in one of these ways:
- Edit the server.xml file as appropriate, then restart the server:
<java-config java-home="JDK_path" ...>
<profiler name="jprobe" enabled="true"
native-library-path="JProbe_dir/profiler" >
<jvm-options>
-Xbootclasspath/p:JProbe_dir/profiler/jpagent.jar
-Xrunjprobeagent -Xnoclassgc
</jvm-options>
</profiler>
</java-config>
See Step 6 for instructions on how to create the JPL file.
- Start the server instance.
- Launch the jpprofiler and attach to Remote Session. The default port is 4444.
- Create the JPL file using the JProbe Launch Pad. Here are the required settings:
- Select Server Side for the type of application.
- On the Program tab, provide the following details:
- Target Server - other_server
- Server home Directory - install_dir
- Server class File - com.iplanet.ias.server.J2EERunner
- Working Directory - install_dir
- Classpath - install_dir/lib/appserv-rt.jar
- Source File Path - source_code_dir (in case you want to get the line level details)
- Server class arguments - (optional)
- Main Package - com.iplanet.ias.server