Sun ONE Web Server 6.1 Programmer's Guide to Web Applications |
Chapter 7
Debugging Web ApplicationsThis chapter provides guidelines for debugging web applications in Sun ONE Web Server, and 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 ONE Web Server 6.1 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, as described in this section:
Sun ONE Application Server debugging is based on the JPDA (Java Platform Debugger Architecture software). For more information, see "JPDA Options."
Using the Administration Interface
To enable debugging:
- Access the Server Manager and click the Java tab.
- Click JVM General.
- Specify the Java home in the Java Home field.
The Java home is the path to the directory where the JDK is installed.
- To enable debugging, select On from the Debug Enabled drop-down list
- Specify debug options in the Debug Options field.
For more information about debug options, see "JPDA Options."
- Click OK.
Editing the server.xml File
To enable debugging, set the following attributes of the JAVA element in the server.xml file:
- Set debug="true" to turn on debugging.
- Add any desired JPDA debugging options in the debugoptions attribute. See "JPDA Options."
- To specify the port to use when attaching the JVM to a debugger, specify address=port_number in the debugoptions attribute.
For details about the server.xml file, see the Sun ONE Web Server 6.1 Administrator's Configuration File Reference.
JPDA OptionsThe default JPDA options 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 DebuggingSun ONE Studio 5 technology can be used for "remote debugging" if you want to manually attach the IDE to a remote Web Server started in debug mode. The steps are as follows:
- Using the Sun ONE Web Server Administration interface, restart the server instance in debug mode (Server Manager > JVM General > Debug Enabled).
- Note the JPDA port number.
- Start the IDE.
- Choose Debug > Start.
- Select the dt_socket method, and then enter the remote machine name and the JPDA port number.
- At that moment, any breakpoint created in the IDE on servlet source code of a deployed application will be active.
For more information about the Sun ONE Studio 5 plugin for Sun ONE Web Server, and about using Sun ONE Studio, see "Using Sun ONE Studio."
Debugging JSPsWhen you use Sun ONE Studio 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.
Generating a Stack Trace for DebuggingYou can generate a Java stack trace for debugging as described here:
http://developer.java.sun.com/developer/technicalArticles/Programmi ng/Stacktrace/
If the -Xrs flag is set (for reduced signal usage) in the server.xml file (under <JVMOPTIONS>), 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 attributes in server.xml.
For more information about the server.xml file, see the Sun ONE Web Server 6.1 Administrator's Configuration File Reference.
LoggingYou can use the Sun ONE Web Server's log files to help debug your applications. For general information about logging, see the Sun ONE Web Server 6.1 Administrator's Guide. For information about configuring logging in the server.xml file, see the Sun ONE Web Server 6.1 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 element in the server.xml file. For details about server.xml file, see the Sun ONE Web Server 6.1 Administrator's Configuration File Reference.
ProfilingYou can use a profiler to perform remote profiling on the Sun ONE Web Server to discover bottlenecks in server-side performance. This section describes how to configure these profilers for use with Sun ONE Web 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 (Java Virtual Machine Profiler Interface) 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 of 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.2/docs/guide/jvmpi/jvmpi.html
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 ONE Web Server in one of these ways:
- Go to the server instance page in the Administration interface, select the Java tab, click the JVM Profiler link, and edit the following fields before clicking OK:
- Edit the server.xml file as appropriate:
<!-- hprof options -->
<PROFILER name="hprof" enabled="true">
<JVMOPTIONS>
-Xrunhprof:file=log.txt,options
</JVMOPTIONS>
</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 ONE Web Server start script. The start script file is instance_dir/start. Change the following line:
PRODUCT_BIN=webservd-wdog
to this:
PRODUCT_BIN=webservd
- 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 webservd
This command lists two webservd 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 Web Server, run the stop script from another window.
% ./stop
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."
- To return your Web Server to its original configuration, undo the changes in steps 1 and 2.
The Optimizeit Profiler
Information about Optimizeit is available at:
http://www.borland.com/optimizeit/
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 Java tab, click the JVM Profiler link, and edit the following fields before selecting OK:
- Edit the server.xml file as appropriate:
<!-- Optimizeit options -->
<PROFILER classpath="Optimizeit_dir/lib/optit.jar"
nativelibrarypath="Optimizeit_dir/lib" enabled="true">
<JVMOPTIONS>
-DOPTIT_HOME=Optimizeit_dir -Xboundthreads -Xrunoii
-Xbootclasspath/a:Optimizeit_dir/lib/oibcp.jar
</JVMOPTIONS>
</PROFILER>In addition, you may need 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."
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 ONE Web Server.