|Oracle GlassFish Server Troubleshooting Guide
Part Number E24941-01
This chapter describes some of the tools, methods, and resources available for troubleshooting Oracle GlassFish Server. Guidelines for evaluating and investigating a problem are provided.
This chapter contains the following sections:
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:
Sometimes the most obvious solutions are overlooked. As you begin your investigation, try the following steps first.
Ensure that your system meets the requirements listed in "Hardware and Software Requirements" in Oracle GlassFish Server 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 Release Notes for known issues related to installation.
Oracle GlassFish Server requires JDK release 6. The minimum (and certified) version of the JDK that is required for Oracle GlassFish Server depends on the operating system:
For supported operating systems except Mac OS, the minimum required version is 1.6.0_17.
For the Mac OS X operating system, the minimum required version is 1.6.0_15.
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, Oracle 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.
$JAVA_HOME/bin in the
PATH to point to the supported JDK version.
Your problem might be related to a known issue for the release. Refer to the Oracle GlassFish Server Release Notes for the latest information regarding known issues and possible workarounds. Also search the GlassFish Issue Tracker at
Oracle GlassFish Server includes complete product documentation. Search the documentation to see if your problem is addressed. 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:
Oracle GlassFish Server Release Notes, which provides the latest information regarding known issues and possible workarounds.
Oracle GlassFish Server Error Message Reference, which lists error messages you might encounter when using GlassFish Server.
Use the product documentation to learn more about Oracle GlassFish Server. The more you know about the product the easier it might be to figure out why something isn't working.
Lists and forums are extremely helpful resources, and are accessed as follows:
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.
What do the logs show? What kind of error message are you getting? For more information about logs, see Examining Log Files. Logs are a good place to start your troubleshooting.
What are you trying to do when the problem occurs and how are you doing it? What is the sequence of events?
Does the problem occur every time you perform the same type of operation, or does it seem random? Can you reproduce the issue?
Have other events or problems occurred that could possibly be related, such as web sessions closing early, exceptions being thrown in your own application logic, components not being correctly deployed or undeployed?
What version of Oracle GlassFish Server are you using? What operating system and version? What JDK version? Many problems are caused simply because system requirements for the release are not met. Refer to the Oracle GlassFish Server Release Notes for the latest information regarding system requirements, and make sure your system meets those requirements.
What resources does your system have, such as memory, disk, and swap space? If system memory is an issue, look for ways to optimize your configuration and consider taking other actions such as adding memory or decreasing system load.
Have any patches been applied? If so, what are the product and operating system patch numbers?
What other products and technologies are installed and being used in the installation?
How many application servers, web servers, and directory servers are installed? What are the products and versions?
How is the web server connected to Oracle GlassFish Server? On the same system?
How is Oracle GlassFish Server connected to the directory server?
What JDBC driver is being used to access the database?
What are your settings?
On which port is Oracle GlassFish Server configured — the default or something else?
What defaults were changed during installation and what are the values?
What other settings were changed from the defaults and what are their values?
What are the parameters related to JVM heap, stack, and garbage collection set to?
What are the JVM options?
What is the permgen size?
OutOfMemoryError:PermGen space errors are common and indicate that you need to increase the permanent generation space available.
Is SSL enabled?
What are your network settings (proxy, firewall, and so on)? What happens if you disable your firewall and attempt the task?
What is different that could have provoked the problem or triggered the event? Was something new added or changed? Have any new applications been deployed? If changes have been made recently, consider backing them out and seeing what happens — does the problem still occur?
Was the feature or functionality working correctly at one time? If so, what changed or happened between then and now?
Is this working on another system? If so, what is different about that environment?
Logging is one of your most important troubleshooting tools. It is the process by which Oracle 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 log files, 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, log information for each Oracle GlassFish Server server instance is captured in a
server.log file. That is, each instance, including the domain administration server (DAS), has an individual log file. By default, the log file for the DAS is located in domain-dir
/logs, and the log file for each instance is located in instance-dir
In addition, for domains that use clustering, Oracle GlassFish Server captures log information for each cluster instance in a
cluster.log file. By default, the
cluster.log file is also located in instance-dir
Oracle recommends using the Administration Console to view logging information. However, you can open a log file in a text editor and search for the module or message in which you are interested. Oracle GlassFish Server also lets you collect log files into a ZIP file, which provides a convenient means to collect and view the log files for an instance or a domain even when it is not running.
You configure the Logging Service by setting attributes in the
logging.properties file. Each server, configuration, instance, and cluster in the Oracle GlassFish Server domain has an individual
logging.properties file. The root directory in which these
logging.properties files are located is the same directory as for the
domain.xml file, typically domain-dir/
config. The default target when configuring logging attributes is the DAS. However, you can optionally target a specific server, instance, or cluster. You can also target a configuration that is shared by one or more instances or clusters. The Logging Service can also be configured using the Administration Console.
Log levels such as
CONFIG, and others can be set to provide different types and amounts of information. The default setting is
INFO. Each Oracle 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 information about using the Administration Console log viewer and logging functions, see the Administration Console online help. For information about using the command line for logging functions, see "Administering the Logging Service" in Oracle GlassFish Server Administration Guide.
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 Oracle 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 "Administering the Monitoring Service" in Oracle GlassFish Server Administration Guide.
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, such as
showrev on Solaris and
rpm on Linux, are helpful in gathering system information.
ps -ef command provides helpful information about processes that are running, including their process identification numbers (PIDs).
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 JVM 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 Oracle GlassFish Server. More information about analyzing the information contained in a thread dump can be found in "An Introduction to Java Stack Traces".
Type the following command:
asadmin generate-jvm-report --type=thread
VisualVM is a Java troubleshooting tool that uses various technologies such as
jvmstat, JMX, 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
JVM command-line tools can be used to provide valuable information about hung Java processes or Java core dumps. These tools include the following:
jstack: Prints Java stack traces of Java threads for a given Java process or core file or a remote debug server.
jinfo: Prints Java configuration information for a given Java process or core file or a remote debug server.
jmap: Prints shared object memory maps or heap memory details for a given process or core file or a remote debug server.
jsadebugd: Attaches to a Java process or core file and acts as a debug server. Remote clients such as
jinfo can attach to the server using Java Remote Invocation Method (RMI).
jhat: Enables Java heap dumps to be browsed using a web browser.
jstat: Displays performance statistics for an instrumented HotSpot JVM.
jps: Lists the instrumented HotSpot JVMs on the target system
These resources were mentioned throughout this chapter and are provided again here for easy reference.
Support subscriptions are available and provide a broad range of support and services to help you get the most out of Oracle GlassFish Server. For more information, visit