Sun GlassFish Communications Server 2.0 Developer's Guide

Chapter 4 Debugging Applications

This chapter gives guidelines for debugging applications in the Sun GlassFish Communications 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:

asadmin start-domain --user adminuser --debug [domain-name]

You can then attach to the server from the Java Debugger (jdb) at its default Java Platform Debugger Architecture (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

Communications Server debugging is based on the JPDA. For more information, see JPDA Options.

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

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

Use the Admin Console. In the developer profile, select the Communications Server component and the JVM Settings tab. In the cluster profile, select the JVM Settings component under the relevant configuration.

Check the Debug Enabled box.

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.

To add JPDA options, add any desired JPDA debugging options in Debug Options. See JPDA Options.

JPDA Options

The default JPDA options in Communications 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

To generate a Java stack trace for debugging, use the asadmin generate-jvm-report --type=thread command. The stack trace goes to the domain-dir/logs/server.log file and also appears on the command prompt screen. For more information about the asadmin generate-jvm-report command, see the Sun GlassFish Communications Server 2.0 Reference Manual.

Application Client Debugging

When the appclient script executes the java command to run the Application Client Container (ACC), which in turn runs the client, it includes on the command line the value of the VMARGS environment variable. You can set this variable to any suitable value. The following example debugging setup is for Windows systems:

VMARGS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8118

The following example debugging setup is for UNIX-based systems:

set VMARGS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8118

For debugging an application client, you should set suspend to y so you can connect the debugger to the client before any code has actually executed. Otherwise, the client may start running and execute past the point you want to examine.

You should use different ports for the server and client if you are debugging both concurrently. For details about setting the port, see JPDA Options.

For information about the appclient script, see Sun GlassFish Communications Server 2.0 Reference Manual.

Sun GlassFish Message Queue Debugging

Sun GlassFish Message Queue has a broker logger, which can be useful for debugging Java Message Service (JMS) applications, 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 GlassFish Message Queue 4.4 Administration Guide.

Enabling Verbose Mode

To have 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.

To start the server in verbose mode, use the --verbose option as follows:

asadmin start-domain --user adminuser --verbose [domain-name]

On Windows platforms, you must perform an extra preparation step if you want to use Ctrl-Break to print a thread dump. In the as-install/asenv.bat file, change AS_NATIVE_LAUNCHER="false" to AS_NATIVE_LAUNCHER="true".

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-\ (on UNIX platforms) or Ctrl-Break (on Windows platforms) prints a thread dump. On UNIX platforms, you can also print a thread dump using the jstack command (see http://java.sun.com/javase/6/docs/technotes/tools/share/jstack.html) or the command kill -QUIT process_id.

Communications Server Logging

You can use the Communications Server’s log files to help debug your applications. Use the Admin Console. In the developer profile, select the Communications Server component. In the cluster profile, select the Stand-Alone Instances component, and select the instance from the table. Then click the View Log Files button in the General Information page.

To change logging settings in the developer profile, select the Logging tab. In the cluster profile, select Logger Settings under the relevant configuration.

For details about logging, click the Help button in the Admin Console.

SIP Message Inspection Log Adapter

You can create your own adapter for logging SIP Message Inspection messages. This adapter must implement the org.jvnet.glassfish.comms.admin.reporter.smi.SmiLogMessageAdapter interface. You can use the example org.jvnet.glassfish.comms.admin.reporter.NullAdapter class as a template:

package org.jvnet.glassfish.comms.admin.reporter;

import javax.servlet.sip.SipServletRequest;
import javax.servlet.sip.SipServletResponse;

public class NullAdapter implements SMILogMessageAdapter {

    public String getLogMessageIncomingRequest(SipServletRequest req) {
        return null;
    }

    public String getLogMessageIncomingResponse(SipServletResponse resp) {
        return null;
    }

    public String getLogMessageOutgoingRequest(SipServletRequest req) {
        return null;
    }

    public String getLogMessageOutgoingResponse(SipServletResponse resp) {
        return null;
    }

    public String getLogMessagePostIncomingRequest(SipServletRequest req, 
            Exception exceptionInCaseOfException) {
        return null;
    }

    public String getLogMessagePostIncomingResponse(SipServletResponse resp, 
            Exception exceptionInCaseOfException) {
        return null;
    }

}

An adapter can log servlet or network manager messages. To determine the type of messages the adapter logs, set SIP Message Inspection properties in one of the following ways:

Use the asadmin set command as follows:
asadmin set config.sip-service.property.smiServletAdapter=classpath;classname asadmin set config.sip-service.property.smiNetworkManagerAdapter=classpath;classname
The classpath and semicolon delimiter are optional. The classpath can be an additional classpath outside the container classpath or a local file system path to the class that doesn't include package names.

The class name must be fully qualified. Periods and other special characters must be escaped. For example:
asadmin set server-config.sip-service.property.smiServletAdapter=org\.mypkg\.myServletAdapterImpl
For more information, see the Sun GlassFish Communications Server 2.0 Reference Manual.
Use the properties table in the SIP Service page in the Admin Console to set the smiServletAdapter and smiNetworkManagerAdapter properties. For more information, click the Help button in the Admin Console.

Here are some suggested uses of an adapter for SIP Message Inspection logging:

You can log or not for a certain interception method.
You can log only for a certain user.
You can collect information from some methods, store it temporarily (for example session attributes), then log it.

For more information about SIP Message Inspection logging, see SIP Message Inspection in Sun GlassFish Communications Server 2.0 Administration Guide.

Profiling Tools

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

Information about comprehensive monitoring and management support in the Java^TM 2 Platform, Standard Edition (J2SE^TM platform) is available at http://java.sun.com/javase/6/docs/technotes/guides/management/index.html.

The NetBeans Profiler

For information on how to use the NetBeans profiler, see http://www.netbeans.org and http://blogs.sun.com/roller/page/bhavani?entry=analyzing_the_performance_of_java.

The HPROF Profiler

The Heap and CPU Profiling Agent (HPROF) is a simple profiler agent shipped with the Java 2 SDK. It is a dynamically linked library that interacts with the Java Virtual Machine Profiler Interface (JVMPI) and writes out profiling information either to a file or to a socket in ASCII or binary format.

HPROF can monitor CPU usage, heap allocation statistics, and 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 technical article at http://java.sun.com/developer/technicalArticles/Programming/HPROF.html.

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

To Use HPROF Profiling on UNIX

Use the Admin Console. In the developer profile, select the Communications Server component and the JVM Settings tab. In the cluster profile, 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 – Select Add, type the HPROF JVM option in the Value field, then check its box. The syntax of the HPROF JVM option is as follows:

-Xrunhprof[:help]|[:param=value,param2=value2, ...]

Here is an example of params you can use:

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

The file parameter determines where the stack dump is written.

Using help lists parameters 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 –

Do not use help in the JVM Option field. This parameter prints text to the standard output and then exits.

The help output refers to the parameters as options, but they are not the same thing as JVM options.

Restart the Communications Server.

This writes an HPROF stack dump to the file you specified using the file HPROF parameter.

The JProbe Profiler

Information about JProbe^TM from Sitraka is available at http://www.quest.com/jprobe/.

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

For details, see the JProbe documentation.

Configure Communications Server using the Admin Console:
1. In the developer profile, select the Communications Server component and the JVM Settings tab. In the cluster profile, select the JVM Settings component under the relevant configuration. Then select the Profiler tab.
2. 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
  Note –
  If any of the configuration options are missing or incorrect, the profiler might experience problems that affect the performance of the Communications Server.
  
  When the server starts up with this configuration, you can attach the profiler.

Set the following environment variable:
JPROBE_ARGS_0=-jp_input=JPL-file-path
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:
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 – as-install
  - Server class File – com.sun.enterprise.server.J2EERunner
  - Working Directory – as-install
  - Classpath – as-install/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
  You must also set VM, Attach, and Coverage tabs appropriately. For further details, see the JProbe documentation. After you have created the JPL file, use this an input to JPROBE_ARGS_0.