Preface Troubleshooting Guide for Java SE 6 with HotSpot VM

1.  Diagnostic Tools and Options

2.  Detailed Tool Descriptions

3.  Troubleshooting Memory Leaks

4.  Troubleshooting System Crashes

5.  Troubleshooting Hanging or Looping Processes

6.  Integrating Signal and Exception Handling

7.  Submitting Bug Reports

A.  Environment Variables and System Properties

B.  Command-Line Options

C.  Fatal Error Log

D.  Summary of Tools in This Release

Preface

This document helps in troubleshooting problems that might occur with applications that are developed using the release of Java Platform, Standard Edition Development Kit 6 (JDK 6 release or Java SE 6 release). In particular, this guide addresses possible problems between the application and the Java HotSpot virtual machine.

See Appendix D, Summary of Tools in This Release for a list of changes to the troubleshooting tools for this release of Java SE compared with the previous release.

This document is currently focused on providing information about the tools and options available for diagnostics and monitoring. It does not yet include information on garbage collection or diagnosing performance issues.

For help in troubleshooting applications that use the Java SE desktop technologies, see the following guide: Troubleshooting Guide for Java SE 6 Desktop Technologies.

Java HotSpot Virtual Machine

The Java HotSpot virtual machine provides a runtime environment for instructions that were generated by a Java compiler. Java SE provides two implementations of the Java virtual machine: client VM and server VM. These two systems are essentially two different just-in-time compilers interfacing with the same runtime system.

• Client VM. This implementation is installed on platforms that are typically used for client, or desktop, applications. The client VM is tuned to reduce startup time and memory footprint. It is invoked by using the -client command-line option when launching an application.
• Server VM. This implementation is installed on all platforms. The server VM is designed for maximum program execution speed. It is invoked by using the -server command-line option when launching an application.

The default implementation depends on the platform and the class of the machine. For full details, see Ergonomics in the 5.0 Java[tm] Virtual Machine.

More information on the Java Hotspot VM can be found at the following locations:

• Java SE HotSpot at a Glance

Who Should Use This Guide

The target audience for this document comprises developers who are working with Java SE 6, as well as support or administration personnel who maintain applications that are deployed with Java SE 6.

This document is intended for readers with a high-level understanding of the components of the Java Virtual Machine, as well as some understanding of concepts such as garbage collection, threads, native libraries, and so on. In addition, it is assumed that the reader is reasonably proficient on the operating system where the Java SE application is installed.

How This Guide Is Organized

The first chapter of this document introduces the various diagnostic and monitoring tools, utilities, options, and system properties that are available for troubleshooting in Java SE 6. The chapter also provides a summary of tools and options by category. Note that tool availability depends on the platform: Solaris Operating System (Solaris OS), Linux, or Windows. Read this chapter to get acquainted with the capabilities of the utilities and options that are available.

The second chapter describes the troubleshooting tools in detail. The chapter also provides a list of the operating system tools and utilities that may be used in conjunction with the Java SE utilities and options. Finally, the chapter describes in detail how you can develop new tools using the APIs provided in the Java SE platform.

The third through fifth chapters suggest procedures to try when you encounter a problem with memory leaks, crashes, or hangs.

The sixth chapter deals with applications that use signal handlers.

The last chapter provides suggestions on what to try before submitting a bug report, guidance on how to submit a report, and suggestions on what data to collect for the report.

Finally, there is an appendix for each of the following reference areas: environment variables, command line options, details about the format of the fatal error report, and a list of tools in this release.

Feedback and Suggestions

Troubleshooting is a very important topic. If you have feedback on this document or if you have suggestions for topics that could be covered in a future version, use the Feedback Form. Fill in the relevant fields and click Send.

Note - Do not use this feedback form for support requests; they will not be answered. Technical support is provided at the Services site for Sun Developer Network.

Other Resources

Troubleshooting information for J2SE 1.5 is described in the Java 2 Platform, Standard Edition 5.0, Troubleshooting and Diagnostic Guide (PDF) .

In addition, the following online troubleshooting resources are available:

• The article Monitoring and Managing Java SE 6 Platform Applications describes the most common problems in Java SE applications and suggests how to use several tools for troubleshooting these problems.
• The Java Tuning White Paper provides performance tuning information, techniques, and pointers for the Java programming language.
• The Performance Documentation for the Java HotSpot VM provides information about performance tuning of the Java HotSpot virtual machine, including garbage collection tuning.
• The Java SE 6 Release Notes, Microsoft Windows Installation (32–bit) provides tips to work around issues that can arise during or following the installation of Java SE on Windows.
• The Java Plug-in Guide provides troubleshooting FAQ as well as information on how to enable tracing when trying to diagnose issues with the Java Plug-in.
• The Java Web Start FAQ has a troubleshooting section dealing with issues that might arise with Java Web Start.
• The bug database can be a useful resource to search for problems and solutions.
• The Solaris Operating System Freeware site is the source for freeware that is packaged for the Solaris Operating System.
• The Sunfreeware.com site (Freeware for Solaris) explains how to download freeware that is packaged for the Solaris Operating System.

Commercial Support

Sun provides a wide range of support offerings, from developer technical support for software developers using Sun development products or technologies, to support for production systems in enterprise environments. Two commercial support options are summarized here: developer technical support and Java mulitplatform support.

Developer Technical Support

Developer technical support is aimed at developers who are using Sun development products or technologies, and who are working at the source-code level of their own applications.

This support offering includes response to technical questions, diagnostic and troubleshooting help, suggestions for best practices, bug escalation, and more.

Java Multiplatform Support

The Java multiplatform support offering is designed to provide production support for shipping releases of Java technology-based applications using Sun's Java runtime environment (JRE) and distributed to end users in heterogeneous environments. This support offering helps to optimize application performance and to reduce time spent keeping applications up and running.

Community Support

Community support can often be obtained using the Java Technology Forums. The forums provide a way to share information and locate solutions to problems. The forums are located here.

Typographic Conventions

The following table describes the typographic conventions that are used in this book.

Typographic Conventions

Shell Prompts in Command Examples

The following table shows the default UNIX system prompt and superuser prompt for shells that are included in the Solaris OS. Note that the default system prompt that is displayed in command examples varies, depending on the Solaris release.

Shell Prompts

Related Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Note - Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

Acknowledgments

Many people contributed technical expertise and other input to this guide: Alan Bateman (major contributor), Tim Bell (major contributor and reviewer), Stephen Bohne, Mandy Chung, Stuart Clements, Uday Dhanikonda (responsible engineering manager), Christine Dorffi, Daniel Fuchs, Jim Holmlund (major contributor and reviewer), David Holmes, Karen Kinnear, Peter LaPierre, James C. Lee, Antonia Lewis (writer), Teresa London, Srinivas Madishetty, Keith McGuigan, Kelly O'Hair, Coleen Phillimore, Leif Samuelsson, Bill Situ, A. Sundararajan, Jesse Suen, Adam Wisnewski.

Document History

The following table tracks the changes in version of this guide.