This chapter introduces the various diagnostic and monitoring tools which can be used with Java Platform Standard Edition Development Kit 6 (JDK 6 or Java SE 6). The tools are described in detail in Chapter 2, Detailed Tool Descriptions.

See Appendix D, Summary of Tools in This Release for a list of tools available in this release of Java SE, as well as the changes since the previous release.

Note - Some of the command-line utilities described in this chapter are experimental. The jstack, jinfo, and jmap utilities are examples of utilities that are experimental. These utilities are subject to change in future JDK releases, and might not be included in future releases.

1.1 Introduction

Most of the command-line utilities described in this chapter are either included in the JDK release or are operating system tools and utilities. Although the JDK command-line utilities are included in the JDK download, it is important to note that they can be used to diagnose issues and monitor applications that are deployed with the Java runtime environment (JRE).

In general, the diagnostic tools and options described in this chapter use various mechanisms to obtain the information they report. In many cases the mechanisms are specific to the virtual machine implementation, operating system, and version of each. Consequently, there is some overlap of the information reported by some of the tools. This should be viewed in the context of the various problems and issues for which these tools are intended. In many cases only a subset of the tools will be applicable to a given issue at a particular point in time.

1.1.1 Command-Line Options With -XX

Command-line options that are prefixed with -XX are specific to the Java HotSpot Virtual Machine. Many of these options are important for performance tuning and diagnostic purposes, and are therefore described in this guide. See B.1 HotSpot VM Command-Line Options.

However, it is important to note that these -XX options are not part of the Java API and can vary from one release to the next.

1.1.2 Limitations

In some cases, the tools described here are available only for some operating systems. In addition, Solaris 10 OS introduced many advanced diagnostic features and tools that can be used in production environments, and many of the native tools are capable of providing information that is specific to the Java runtime environment.

The format of log files and of other output from command-line utilities or options is version-specific. For example, if you develop a script that relies on the format of the fatal error log, then this script might cease to work as expected if the format of the log file changes in the future.

1.1.3 Developing New Tools

In addition to the tools described in this document, you can develop new tools using the APIs that are provided with the JDK release. See 2.17 Developing Diagnostic Tools.

1.2 Summary of Tools, Options, and Commands

The tools and options are divided into the following categories, where certain tools might fall into more than one category. The tools and options are described in detail in further sections.

Post-mortem diagnostics. These tools and options can be used to diagnose a problem after an application has crashed. See 1.2.1 Tools and Options for Post-mortem Diagnostics.
Hung processes. These tools can be used to investigate a hung or deadlocked process. See 1.2.2 Tools and Options for Hung Processes.
Monitoring. These tools can be used to monitor a running application. See 1.2.3 Tools and Options for Monitoring.
Other. These tools and options can be used to help diagnose other issues. See 1.2.4 Other Tools, Options, Variables, and Properties.
Operating system tools. These tools are provided by the specific operating systems. See 2.16 Operating-System-Specific Tools.

1.2.1 Tools and Options for Post-mortem Diagnostics

This section summarizes the options and tools that are designed for post-mortem diagnostics. If an application crashes, these options and tools can be used to obtain additional information, either at the time of the crash or later using information from the crash dump.

Tool or Option	Description and Usage
Fatal Error Log	When a fatal error occurs, an error log is created. This file contains much information obtained at the time of the fatal error. In many cases it is the first item to examine when a crash occurs. See Appendix C, Fatal Error Log.
`-XX:+HeapDumpOnOutOfMemoryError` option	This command-line option specifies the generation of a heap dump when the VM detects a native out-of-memory error. See B.1.2 `-XX:+HeapDumpOnOutOfMemoryError` Option .
`-XX:OnError` option	This command-line option specifies a sequence of user-supplied scripts or commands to be executed when a fatal error occurs. For example, on Windows, this option can execute a command to force a crash dump. This option is very useful on systems where a post-mortem debugger is not configured. See B.1.3 `-XX:OnError=` Option .
`-XX:+ShowMessageBoxOnError`	This command-line option suspends a process when a fatal error occurs. Depending on the user response, the option can launch the native debugger (for example, `dbx`, `gdb`, `msdev`) to attach to the VM. See B.1.4 `-XX:+ShowMessageBoxOnError` Option .
Other `-XX` options	Several other `-XX` command-line options can be useful in troubleshooting. See B.1.5 Other `-XX` Options .
Java VisualVM (post-mortem use on Solaris OS and Linux only)	This utility can analyze a core dump by providing a readable display of the core dump in the form of a heap dump and a thread dump, as well as overview information (for example, JVM arguments, system properties, and so forth).
`jdb` utility	Debugger support includes an `AttachingConnector`, which allows `jdb` and other Java language debuggers to attach to a core file. This can be useful when trying to understand what each thread was doing at the time of a crash. See 2.4 `jdb` Utility .
`jhat` utility	This utility provides a convenient means to browse the object topology in a heap dump. See 2.5 `jhat` Utility .
`jinfo` utility (post-mortem use on Solaris OS and Linux only)	This utility can obtain configuration information from a core file obtained from a crash or from a core file obtained using the `gcore` utility. See 2.6 `jinfo` Utility .
`jmap` utility (post-mortem use on Solaris OS and Linux only)	This utility can obtain memory map information, including a heap histogram, from a core file obtained from a crash or from a core obtained using the `gcore` utility. See 2.7 `jmap` Utility .
`jsadebugd` daemon (Solaris OS and Linux only)	The Serviceability Agent Debug Daemon ( `jsadebugd`) attaches to a Java process or to a core file and acts as a debug server. See 2.10 `jsadebugd` Daemon .
`jstack` utility	This utility can obtain Java and native stack information from a Java process. On Solaris OS and Linux the utility can get the information also from a core file or a remote debug server. See 2.11 `jstack` Utility .
Native tools	Each operating system has native tools and utilities that can be used for post-mortem diagnosis. See 2.16 Operating-System-Specific Tools.

1.2.2 Tools and Options for Hung Processes

The options and tools in this list can help in scenarios involving a hung or deadlocked process. These tools do not require any special options to start the application.

Tool or Option	Description and Usage
Ctrl-Break handler (Ctrl-\ or `kill -QUIT` `pid` on Solaris OS and Linux, Ctrl-Break on Windows)	This key combination performs a thread dump as well as deadlock detection. The Ctrl-Break handler can optionally print a list of concurrent locks and their owners, as well as a heap histogram. See 2.15 Ctrl-Break Handler.
`jdb` utility	Debugger support includes attaching connectors, which allow `jdb` and other Java language debuggers to attach to a process. This can help show what each thread is doing at the time of a hang or deadlock. See 2.4 `jdb` Utility .
`jhat` utility	This utility provides a convenient means to browse the object topology in a heap dump. See 2.5 `jhat` Utility .
`jinfo` utility	This utility can obtain configuration information from a Java process. See 2.6 `jinfo` Utility .
`jmap` utility	This utility can obtain memory map information, including a heap histogram, from a Java process. On Solaris OS and Linux, the `-F` option can be used if the process is hung. See 2.7 `jmap` Utility
`jsadebugd` daemon (Solaris OS and Linux only)	The Serviceability Agent Debug Daemon ( `jsadebugd`) attaches to a Java process or to a core file and acts as a debug server. See 2.10 `jsadebugd` Daemon .
`jstack` utility	This utility can obtain Java and native stack information from a Java process. On Solaris OS and Linux the `-F` option can be used if the process is hung. See 2.11 `jstack` Utility .
Native tools	Each operating system has native tools and utilities that can be useful in hang or deadlock situations. See 2.16 Operating-System-Specific Tools.

1.2.3 Tools and Options for Monitoring

These tools are designed for monitoring applications that are running at the time.

Tool or Option	Description and Usage
Java VisualVM	This utility provides a visual interface for viewing detailed information about Java applications while they are running on a Java virtual machine. This information can be used in troubleshooting local and remote applications, as well as for profiling local applications. See 2.2 Java VisualVM.
JConsole utility	This utility is a monitoring tool that is based on Java Management Extensions (JMX). The tool uses the built-in JMX instrumentation in the Java virtual machine to provide information on performance and resource consumption of running applications. See 2.3 JConsole Utility.
`jmap` utility	This utility can obtain memory map information, including a heap histogram, from a Java process, a core file, or a remote debug server. See 2.7 `jmap` Utility .
`jps` utility	This utility lists the instrumented HotSpot Virtual Machines on the target system. The utility is very useful in environments where the VM is embedded, that is, it is started using the JNI Invocation API rather than the `java` launcher. See 2.8 `jps` Utility .
`jstack` utility	This utility can obtain Java and native stack information from a Java process. On Solaris OS and Linux the utility can get the information also from a core file or a remote debug server. See 2.11 `jstack` Utility .
`jstat` utility	This utility uses the built-in instrumentation in the HotSpot VM to provide information on performance and resource consumption of running applications. The tool can be used when diagnosing performance issues, and in particular issues related to heap sizing and garbage collection. See 2.12 `jstat` Utility .
`jstatd` daemon	This tool is an RMI server application that monitors the creation and termination of instrumented Java virtual machines and provides an interface to allow remote monitoring tools to attach to VMs running on the local host. See 2.13 `jstatd` Daemon .
`visualgc` utility	This utility provides a graphical view of the garbage collection system. As with `jstat`, it uses the built-in instrumentation of the HotSpot VM. See 2.14 `visualgc` Tool .
Native tools	Each operating system has native tools and utilities that can be useful for monitoring purposes. For example, the dynamic tracing (DTrace) capability introduced in Solaris 10 OS performs advanced monitoring. See 2.16 Operating-System-Specific Tools.

1.2.4 Other Tools, Options, Variables, and Properties

In addition to the tools that are designed for specific types of problems, these tools, options, variables, and properties can help in diagnosing other issues.

Tool or Option	Description and Usage
HPROF profiler	This simple profiler can present CPU usage, heap allocation statistics, contention profiles, heap dumps, and states of all the monitors and threads in the Java virtual machine. HPROF is useful in analyzing performance, lock contention, memory leaks, and other issues. See 2.1 HPROF - Heap Profiler.
`jhat` utility	This utility is useful in diagnosing unnecessary object retention (or memory leaks). It can be used to browse an object dump, view all reachable objects in the heap, and show which references are keeping an object alive. See 2.5 `jhat` Utility .
`jinfo` utility	This utility can dynamically set, unset, and change the values of certain Java VM flags for a specified Java process. On Solaris OS and Linux, it can also print configuration information. See 2.6 `jinfo` Utility .
`jrunscript` utility	This utility is a command-line script shell, which supports both interactive and batch-mode script execution. See 2.9 `jrunscript` Utility .
Sun Studio `dbx` debugger	This is an interactive, command-line debugging tool, which allows you to have complete control of the dynamic execution of a program, including stopping the program and inspecting its state.
Sun Studio Performance Analyzer	This tool can help you assess the performance of your code, identify potential performance problems, and locate the part of the code where the problems occur. The Performance Analyzer can be used from the command line or from a graphical user interface.
Sun's Dataspace Profiling: DProfile	This tool provides insight into the flow of data within Sun computing systems, helping you identify bottlenecks in both software and hardware. DProfile is supported in the Sun Studio 11 compiler suite through the Performance Analyzer GUI.
`-Xcheck:jni` option	This option is useful in diagnosing problems with applications that use the Java Native Interface (JNI) or that employ third-party libraries (some JDBC drivers, for example). See B.2.1 `-Xcheck:jni` Option .
`-verbose:class` option	This option enables logging of class loading and unloading. See B.2.2 `-verbose:class` Option .
`-verbose:gc` option	This option enables logging of garbage collection information. See B.2.3 `-verbose:gc` Option .
`-verbose:jni` option	This option enables logging of JNI. See B.2.4 `-verbose:jni` Option .
`JAVA_TOOL_OPTIONS` environment variable	This environment variable allows you to specify the initialization of tools, specifically the launching of native or Java programming language agents using the `-agentlib` or `-javaagent` options. See A.2 `JAVA_TOOL_OPTIONS` Environment Variable .
`java.security.debug` system property	This system property controls whether the security checks in the JRE of the Java print trace messages during execution. See A.3 `java.security.debug` System Property .