test

Oracle GlassFish Server 3.0.1 Troubleshooting Guide

Chapter 1 Overview of GlassFishTM Server Troubleshooting

This chapter describes some of the tools, methods, and resources available for troubleshooting Sun GlassFish GlassFish Server 3.0.1. Guidelines for evaluating and investigating a problem are provided.

This chapter contains the following sections:

Identifying the Problem

Application servers are typically deployed in complex operating environments and involve many technologies, products, and tools. Understanding and diagnosing problems in enterprise software with many components performing many tasks can be a challenge. This section describes how to get started , and contains the following topics:

First Steps

Sometimes the most obvious solutions are overlooked. As you begin your investigation, try the following steps first.

Verify System Requirements and Configuration

Ensure that your system meets the requirements listed in Hardware and Software Requirements in Oracle GlassFish Server 3.0.1 Release Notes. Problems are likely to arise if you attempt to install on a platform that is not supported or on a system that in some other way does not meet release requirements. Also see Known Issues in Oracle GlassFish Server 3.0.1 Release Notes for known issues related to installation.

GlassFish Server 3.0.1 requires JDKTM release 6. The minimum (and certified) version of the JDK that is required for GlassFish Server depends on the operating system:

If necessary, download and install the required JDK software.

On Solaris, Linux, and Windows systems, JDK software is available from the Java SE downloads page.

For Mac OS X systems, GlassFish Server uses the JDK that is part of the Macintosh operating system. If necessary, obtain the required JDK version from the Mac OS X Updates site.

Also ensure that the JAVA_HOME environment variable on your system points to the JDK installation directory and not the Java Runtime Environment (JRE) software.

Set JAVA_HOME and $JAVA_HOME/bin in the PATH to point to the supported JDK version.

Review Known Issues

Your problem might be related to a known issue for the release. Refer to the Oracle GlassFish Server 3.0.1 Release Notes for the latest information regarding known issues and possible workarounds. Also search the GlassFish Issue Tracker at https://glassfish.dev.java.net/servlets/ProjectIssues.

Search the Product Documentation

GlassFish Server includes complete product documentation. Search the documentation to see if your problem is addressed. Documentation is available at http://docs.sun.com/coll/1343.9. See GlassFish Server Documentation Set for the books in the documentation set and a description of their contents. Also see the Administration Console online help for detailed information about performing administrative tasks using the graphical interface.

The following books will be especially helpful for troubleshooting:

Use the product documentation to learn more about GlassFish Server 3.0.1. The more you know about the product the easier it might be to figure out why something isn't working.

Search the GlassFish Mailing Lists and Forums

Lists and forums are extremely helpful resources, and are accessed as follows:

Search the SunSolve Knowledgebase

SunSolveSM is Sun's informational and patch database service with a browseable directory of all publicly available Sun Microsystems support documents. SunSolve is available at http://sunsolve.sun.com. Additional resources are also available for customers with support contracts.

Gathering Information

Troubleshooting and analysis require information. The more information you have the easier it is to classify a problem and search for its solution. Detailed information will also be necessary should you need to contact others for support, either through a community mailing list or through more formal Sun support channels.

As you continue your investigation, consider the following questions.

When Does the Problem Occur?

What Is Your Environment?

What Is Your System Configuration?

What Is Different?

Examining Log Files

Logging is one of your most important troubleshooting tools. It is the process by which GlassFish Server captures data about events that occur during server operation, such as configuration errors, security failures, or server malfunction. This data is recorded in a log file, and is usually your first source of information when Enterprise Server problems occur. The primary purpose of log files is to provide troubleshooting information. Analyzing the log files can help determine the health of the server and identify problem areas.

By default all GlassFish Server log information is captured in the server.log file, typically located in domain-dir/logs. You can view logging information by using the Administration Console or the asadmin utility. You can also open the server.log file in a text editor and search for the module that you are interested in.

For information about using the Administration Console log viewer and logging functions, see the Administration Console online help. For information about viewing logging information from the command line, see Viewing Log Information in Oracle GlassFish Server 3.0.1 Administration Guide.

Logging is configured by editing the logging.properties file, located by default in the same directory as the domain.xml file, typically domain-dir/config. Logging can also be configured using the Administration Console.

Log levels such as SEVERE, WARNING, INFO, CONFIG, and others can be set to provide different types and amounts of information. The default setting is INFO. Each GlassFish Server module has its own logger, and each logger has its own namespace. Log levels can be set globally for all loggers, or individually for module-specific loggers.

For complete details about logging see Chapter 7, Administering the Logging Service, in Oracle GlassFish Server 3.0.1 Administration Guide.

Monitoring the System

Monitoring is another helpful tool. It is the process of reviewing the statistics of a system to improve performance or solve problems. By monitoring the state of various components and services deployed in GlassFish Server you can identify performance bottlenecks, predict failures, perform root cause analysis, and ensure that everything is functioning as expected. For more information about monitoring, including JConsole information, see Chapter 8, Administering the Monitoring Service, in Oracle GlassFish Server 3.0.1 Administration Guide.

Troubleshooting Tools

Several tools are available that can be used to collect information for troubleshooting purposes. This section provides basic information about some of them, and includes the following:

Operating System Utilities

Operating system utilities, such as pkginfo and showrev on Solaris and rpm on Linux, are helpful in gathering system information.

The ps -ef command provides helpful information about processes that are running, including their process identification numbers (PIDs).

Stack Traces and Thread Dumps

A stack trace is a user-friendly snapshot of the threads and monitors in a Virtual Machine for the Java platform (Java Virtual Machine or JVMTM machine). A thread dump shows what every thread in a JVM is doing at a given time and is useful in debugging. When the application server freezes, hangs, or becomes sluggish for no apparent reason, you should generate and analyze a thread dump.

This section explains how to obtain a thread dump for GlassFish Server. More information about analyzing the information contained in a thread dump can be found in “An Introduction to Java Stack Traces” (http://java.sun.com/developer/technicalArticles/Programming/Stacktrace).

ProcedureTo Obtain a Server Thread Dump

  1. Type the following command:


    asadmin generate-jvm-report --type=thread
See Also

generate-jvm-report(1)

VisualVM

VisualVM is a Java troubleshooting tool that uses various technologies such as jvmstat, JMXTM, and Attach API to access monitored applications. VisualVM is a tool for visualizing data sources and by default visualizes the following types: applications, hosts, snapshots, core dumps, heap dumps, and thread dumps. These data sources are visualized in VisualVM so that they can be monitored for the purposes of analysis, management, and troubleshooting. VisualVM is commonly used to detect memory leaks.

VisualVM has a GlassFish plugin that enhances monitoring of hosted applications by adding specialized overview, a tab for monitoring the HTTP Service, and the ability to visually select and monitor any of the deployed web applications. You can experiment with VisualVM troubleshooting capabilities, but note that various features depend on the Java versions used in the client and server. Depending on your configuration, you might only get parts of the VisualVM features. For more information about VisualVM, see https://visualvm.dev.java.net.

JVM Command-Line Tools

JVM command-line tools can be used to provide valuable information about hung Java processes or Java core dumps. These tools include the following:

Where to Go for More Information

These resources were mentioned throughout this chapter and are provided again here for easy reference.

GlassFish Server Support

Support subscriptions are available and provide a broad range of support and services to help you get the most out of GlassFish Server. For more information, visit http://www.oracle.com/support/premier/index.html.