Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Developer's Guide

- Previous: Chapter 3 Assembling and Deploying Applications
- Next: Part II Developing Applications and Application Components

# Chapter 4 Debugging Applications

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

- Enabling Debugging

- JPDA Options

- Generating a Stack Trace for Debugging

- The Java Debugger

- Using an IDE

- Sun Java System Message Queue Debugging

- Enabling Verbose Mode

- Logging

- Profiling

# 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 9009. For example, for UNIX systems:

    jdb -attach 9009

For Windows:

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

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.

## To set the server to automatically start up in debug mode

1. Select the JVM Settings component under the relevant configuration in the Administration Console.

2. Check the Debug Enabled box.

3. To specify a different port (from 9009, the default) to use when attaching the JVM to a debugger, specify `address=` port-number in the Debug Options field.

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

##### See Also

For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

# JPDA Options

The default JPDA options in Application Server are as follows:

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

For Windows, you can change `dt_socket` to `dt_shmem`.

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 9009, 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 at `http://java.sun.com/products/jpda/doc/conninv.html#Invocation`.

# Generating a Stack Trace for Debugging

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

http://developer.java.sun.com/developer/technicalArticles/Programming/Stacktrace/

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 Platform Edition 8.1 2005Q2 Update 2 Administration Reference.

# The Java Debugger

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

    jdb -attach 9009

For Windows:

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

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

Java Platform Debugger Architecture - The Java Debugger: `http://java.sun.com/products/jpda/doc/soljdb.html`

Java Platform Debugger Architecture - Connecting with JDB: `http://java.sun.com/products/jpda/doc/conninv.html#JDB`

You can attach to the Application Server using any JPDA compliant IDE debugger, including NetBeans, Sun Java Studio, JBuilder, Eclipse, and so on.

# Using an IDE

You can use an IDE (integrated development environment) with the Application Server to take advantage of the IDE's debugging features.

## To use the NetBeans 3.6 IDE with the Application Server

1. Download the latest version of NetBeans from `http://www.netbeans.org`.

2. Set up the classpath in NetBeans to compile J2EE applications using the standard J2EE 1.4 API libraries provided with the Application Server.

   Perform the following steps in the NetBeans IDE:

   1. In the Menu bar, click on the File menu and select Mount Filesystem.

   2. In the wizard dialog box, select Archive Files as the Filesystem type and click Next.

   3. Navigate the file chooser to the Application Server directory install-dir`/lib`.

   4. Select `j2ee.jar`. To use Sun-specific public APIs provided in the Application Server, select the `appserv-ext.jar` archive as well. Click Finish.

      The `j2ee.jar` file should appear in the list of mounted file systems under the Editing pane inside the Filesystems tab of the NetBeans IDE. You can now import J2EE 1.4 API packages in your source files and compile the source files.

3. Build your application in the NetBeans IDE.

4. Assemble your application into a J2EE archive file (WAR, JAR, RAR or EAR file) and deploy it to the Application Server.

5. Start the Application Server with debugging enabled. See Enabling Debugging.

6. Attach to the Application Server using the NetBeans IDE debugger:

   1. Click on the Debug menu, select Start Session, then select Attach.

   2. In the Attach dialog box, make sure the host (default `localhost`) and port (default `9009`) correspond to the host and JPDA debug port of the Application Server. Click OK.

      The Output Window of the Debugger Console should display the message `Connection established`.

7. Set break points in your source file in the NetBeans IDE as usual, and run the application.

8. When finished with debugging, detach from the server by clicking Finish in the Debug menu.

# 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 3 2005Q4 Administration Guide.

# Enabling Verbose Mode

If you want to see the server logs and messages printed to `System.out` 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 console or terminal window 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 using the Administration Console. For details, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

# Logging

You can use the Application Server’s log files to help debug your applications. In the Administration Console, select the Application Server component, then click on the Open Log Viewer button in the General Information page. For details about logging, see the Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Administration Guide.

# Profiling

You can use a profiler to perform remote profiling on the Application Server to discover bottlenecks in server-side performance. This section describes how to configure these profilers for use with the Application Server:

- The HPROF Profiler

- The Optimizeit Profiler

Information about comprehensive monitoring and management support in the JavaTM 2 Platform, Standard Edition (J2SETM platform) version 5.0 is available at `http://java.sun.com/j2se/1.5.0/docs/guide/management/index.html`.

## 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 `http://java.sun.com/j2se/1.4.2/docs/guide/jvmpi/jvmpi.html#hprof`.

Once HPROF is enabled using the following instructions, its libraries are loaded into the server process.

### To use HPROF profiling on UNIX

1. Configure the Application Server using the Administration Console:

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

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

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

You can purchase OptimizeitTM from Borland at `http://www.borland.com/optimizeit`.

Once Optimizeit is enabled using the following instructions, its libraries are loaded into the server process.

### To enable remote profiling with Optimizeit

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

2. Configure the Application Server using the Administration Console:

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

   2. 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:startAudit=t
            -Xbootclasspath/p:/Optimizeit-dir/lib/oibcp.jar

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

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

4. Restart the Application Server.

   When the server starts up with this configuration, you can attach the profiler.

##### See Also

For further details, see the Optimizeit documentation.

##### Troubleshooting

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

- Previous: Chapter 3 Assembling and Deploying Applications
- Next: Part II Developing Applications and Application Components

- © 2010, Oracle Corporation and/or its affiliates