Diagnostic Tools and Options

This chapter introduces the various diagnostic and monitoring tools which can be used with Java Platform, Standard Edition Development Kit 7 (JDK 7). 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 the JDK, as well as the changes since the previous release.

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. For details, see the latest dbx documentation, located at the Sun Studio Program Debugging site. 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. For details, see the Sun Studio Performance Analyzer site. 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. For information, see the Cool Tools Community site under Other Sun Tools. -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.