Chapter 4 Debugging J2EE Applications

This chapter gives guidelines for debugging applications in Sun Java System Application Server. It includes the following sections:

Enabling Debugging

When you enable debugging, you enable both local and remote debugging. To start the server in debug mode, use the --debug option as follows:

You can then attach to the server from the debugger at its default JPDA port, which is 1044. For example, for UNIX systems:

Sun Java System Application Server debugging is based on the JPDA (Java Platform Debugger Architecture). For more information, see JPDA Options.

You can enable debugging even when the application server is started without the --debug option. This is useful if you start the application server from the Windows Start Menu or if you want to make sure that debugging is always turned on. You can set the server to automatically start up in debug mode using the Administration Console:

Select the JVM Settings component under the relevant configuration.

Check the Debug Enabled box.

To specify a different port (from 1044, the default) to use when attaching the JVM to a debugger, specify address=port_number in the Debug Options field.

If you wish to add JPDA options, add any desired JPDA debugging options in Debug Options. See JPDA Options.

JPDA Options

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 a different port (from 1044, the default) 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:

Generating a Stack Trace for Debugging

You can generate a Java stack trace for debugging as described here if the Sun Java System Application Server is in verbose mode (see Enabling Verbose Mode):

The stack trace goes to the domain_dir/logs/server.log file and also appears on the command prompt screen.

If the -Xrs flag is set (for reduced signal usage) in the domain.xml file (under <jvm-options>), comment it out before generating the stack trace. If the -Xrs flag is used, the server might simply dump core and restart when you send the signal to generate the trace. For more about the domain.xml file, see the Sun Java System Application Server Reference.

The Java Debugger

The Java Debugger (jdb) helps you find and fix bugs in Java language programs. When using the jdb debugger with Sun Java System Application Server, you must attach to the server from the debugger at its default JPDA port, which is 1044. For example, for UNIX systems:

Sun Java System Message Queue Debugging

Sun 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.

Enabling Verbose Mode

If you want to see the server logs and messages printed to System.out or System.err on your command prompt screen, you can start the server in verbose mode. This makes it easy to do simple debugging using print statements, without having to view the server.log file every time.

When the server is in verbose mode, messages are logged to the client in addition to the log file. In addition, pressing Ctrl-C stops the server and pressing Ctrl-\ prints a thread dump. To start the server in verbose mode, use the --verbose option as follows:

You can enable verbose mode even when the application server is started without the --verbose option. This is useful if you start the application server from the Windows Start Menu or if you want to make sure that verbose mode is always turned on.

You can set the server to automatically start up in verbose mode using the Administration Console. Select the Logger Settings component under the relevant configuration, then check the Log Messages to Standard Error box. For details, see the Sun Java System Application Server Administration Guide.

Logging

You can use the Sun Java System Application Server’s log files to help debug your applications. Select the Logger Settings component under the relevant configuration. For details about logging, see the Sun Java System Application Server Administration Guide.

Profiling

You 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

The Optimizeit Profiler

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.

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:

Once HPROF is enabled 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 using the Administration Console:

Select the JVM Settings component under the relevant configuration, then select the Profiler tab.

Edit the following fields:

Profiler Name: hprof

Profiler Enabled: true

Classpath: (leave blank)

Native Library Path: (leave blank)

JVM Option: For each of these options, select Add, type the option in the Value field, then check its box:

-Xrunhprof:file=log.txt,options

Here is an example of options you can use:

-Xrunhprof:file=log.txt,thread=y,depth=3

The file option determines where the stack dump is written in Step 2.

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

Restart the Application Server. This writes an HPROF stack dump to the file you specified using the file HPROF option in Step 1.

The Optimizeit Profiler

Once Optimizeit is enabled using the following instructions, its libraries are loaded into the server process. To enable remote profiling with Optimizeit, do one of the following:

Configure your operating system:

On Solaris, add Optimizeit_dir/lib to the LD_LIBRARY_PATH environment variable.

On Windows, add Optimizeit_dir/lib to the PATH environment variable.

Configure Sun Java System Application Server using the Administration Console:

Select the JVM Settings component under the relevant configuration, then select the Profiler tab.

Edit the following fields:

Profiler Name: optimizeit

Profiler Enabled: true

Classpath: Optimizeit_dir/lib/optit.jar

Native Library Path: Optimizeit_dir/lib

JVM Option: For each of these options, select Add, type the option in the Value field, then check its box:

    -DOPTITHOME=Optimizeit_dir
    -Xrunpri
    -Xbootclasspath/Optimizeit_dir/lib/oibcp.jar

In addition, you might have to set the following in your server.policy file. For more information about the server.policy file, see “The server.policy File” on page 52.

  grant codeBase "file:Optimizeit_dir/lib/optit.jar" {
    permission java.security.AllPermission;
  };

Restart the Application Server.

When the server starts up with this configuration, you can attach the profiler. For further details, see the Optimizeit documentation.

Previous Contents Index Next
Sun Java System Application Server Platform Edition 2004Q4 Beta Developer's Guide


Note	If any of the configuration options are missing or incorrect, the profiler might experience problems that affect the performance of the Sun Java System Application Server.