Sun logo      Previous      Contents      Index      Next     

J2EE 1.4 Application Server Developer's Guide

Chapter 4
Debugging J2EE Applications

This chapter gives guidelines for debugging applications in J2EE 1.4 Application Server. It includes the following sections:

The domain.xml file described in this chapter is located at domain_dir/config/domain.xml. For more information about this file, see the J2EE 1.4 Application Server Administrator’s Configuration File Reference.

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:

asadmin start-domain --debug [domain_name]

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

jdb -attach 1044

For Windows:

jdb -connect com.sun.jdi.SocketAttach:port=1044

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 in one of these ways:

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

Using the Administration Console

To enable debugging for each server restart:

  1. Login to the Administration Console by going to the following URL in your web browser:

    2. http://localhost:4848/asadmin

  2. Go to the Application Server page.
  3. Select the JVM Settings tab and the General option.
  4. Check the Debug Enabled box.
  5. 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.
  6. If you wish to add JPDA options, add any desired JPDA debugging options in Debug Options. See "JPDA Options".
  7. Select the Save button.

Editing the domain.xml File

To enable debugging for each server restart, set the following attributes of the java-config element in the domain.xml file:

For details about the domain.xml file, see the J2EE 1.4 Application Server Administrator’s Configuration File Reference.

JPDA Options

The default JPDA options in J2EE 1.4 Application Server are as follows:

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044

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:

http://java.sun.com/products/jpda/doc/conninv.html#Invocation

The Java Debugger

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

jdb -attach 1044

For Windows:

jdb -connect com.sun.jdi.SocketAttach:port=1044

For more information about the jdb debugger, see the following links:

http://java.sun.com/products/jpda/doc/soljdb.html

http://java.sun.com/products/jpda/doc/conninv.html#JDB

http://java.sun.com/products/jdk/1.2/debugging/JDBTutorial.html

Generating a Stack Trace for Debugging

You 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 domain.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 domain_dir/logs/server.log file. If the server was started with the --verbose option, or if verbose mode is always on, the stack trace also appears on the command prompt screen.

For more about the domain.xml file, see the J2EE 1.4 Application Server Administrator’s Configuration File Reference.

Sun ONE Message Queue Debugging

Sun ONE 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 ONE 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:

asadmin start-domain --verbose [domain_name]

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 in one of these ways:

Using the Administration Console

To enable verbose mode for each server restart:

  1. Login to the Administration Console by going to the following URL in your web browser:

    2. http://localhost:4848/asadmin

  2. Go to the Application Server page.
  3. Select the Logging tab and the General option.
  4. Check the Log Messages to Standard Error box.
  5. Select the Save button.

Editing the domain.xml File

To enable verbose mode for each server restart, set the attributes of the log-service element in the domain.xml file.

You can send exceptions to the client in addition to the log file. Set the following parameter in domain.xml. If the client is a browser, exceptions are displayed in the browser.

<log-service ... log-to-console=true ... />

For details about the domain.xml file, see the J2EE 1.4 Application Server Administrator’s Configuration File Reference.

Logging

You can use the J2EE 1.4 Application Server’s log files to help debug your applications. For general information about logging, see the J2EE 1.4 Application Server Administrator’s Guide. For information about configuring logging in the domain.xml file, see the J2EE 1.4 Application Server Administrator’s Configuration File Reference.

Profiling

You can use a profiler to perform remote profiling on the J2EE 1.4 Application Server to discover bottlenecks in server-side performance. This section describes how to configure these profilers for use with J2EE 1.4 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:

  1. Configure J2EE 1.4 Application Server in one of these ways:
    • Go to the Application Server page in the Administration Console, select the JVM Settings tab, select the Profiler option, and edit the following fields before selecting Save:
      • 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

    • Edit the domain.xml file as appropriate:

      •   <!-- hprof options -->
        <profiler name="hprof" enabled="true">
          <jvm-options>
            -Xrunhprof:file=log.txt,options
          </jvm-options>
        </profiler>

      Note

      Do not use the -Xrs flag.

      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

      Note

      The cpu and monitor options don’t work in JDK 1.4.

  2. You must also change a line in the J2EE 1.4 Application Server start script. The start script file is domain_dir/bin/startserv. Change the following line:

    3. PRODUCT_BIN=appservd-wdog

    to this:

    PRODUCT_BIN=appservd

  3. 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.
  4. In another window or terminal, find the process ID of the server process.

    5. % 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.

  5. Send a SIGQUIT signal (signal 3) to the child process:

    6. % kill -QUIT child_PID

  6. To stop the Application Server, run the stop script from another window.

    7. % ./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".

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

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

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 J2EE 1.4 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 domain.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 J2EE 1.4 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:

  1. Install JProbe 3.0.1.1. This version supports JDK 1.4. For details, see the JProbe documentation.
  2. Configure J2EE 1.4 Application Server in one of these ways:
    • Go to the Application Server page in the Administration Console, select the JVM Settings tab, type a path to JDK 1.4.0 or 1.4.0_01 in the Java Home field, and select Save.

      Select the Profiler option, and edit the following fields before selecting Save and restarting the server:

      • Profiler Name: jprobe
      • Profiler Enabled: true
      • Classpath: (leave blank)
      • Native Library Path: JProbe_dir/profiler
      • JVM Option: For each of these options, select Add, type the option in the Value field, then check its box:

        -Xbootclasspath/p:JProbe_dir/profiler/jpagent.jar

        -Xrunjprobeagent

        -Xnoclassgc

    • Edit the domain.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>

      The JDK_path must point to JDK 1.4.0 or 1.4.0_01.

      Note

      JProbe does not work with the JDK version that is bundled with J2EE 1.4 Application Server.

      Note

      If any of the configuration options are missing or incorrect, the profiler may experience problems that affect the performance of the J2EE 1.4 Application Server.

  1. Set the following environment variable:

    2. JPROBE_ARGS_0=-jp_input=JPL_file_path

  1. Start the server.
  2. Launch the jpprofiler and attach to Remote Session. The default port is 4444.
  3. Create the JPL file using the JProbe Launch Pad. Here are the required settings:
    1. Select Server Side for the type of application.
    2. On the Program tab, provide the following details:
      • Target Server - other_server
      • Server home Directory - install_dir
      • Server class File - com.sun.enterprise.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.sun.enterprise.server


Previous      Contents      Index      Next     

Copyright 2003 Sun Microsystems, Inc. All rights reserved.