This chapter introduces the various diagnostic and monitoring tools which can be used with the Java Development Kit (JDK).
The tools are described in detail in "Detailed Tool Descriptions".
For a list of tools available in the current release of the JDK, as well as the changes since the previous release, see "Summary of Tools in This Release".
|
Note: Some of the command-line utilities described in this chapter are experimental. The |
This chapter contains the following sections:
Most of the command-line utilities described in this chapter are either included in the JDK release or are native operating system (OS) 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 VM implementation, OS, and release. 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.
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. For more information on command-line options used by the HotSpot VM, see "HotSpot VM Command-Line Options".
|
Note: The |
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 JRE.
The format of log files and of other output from command-line utilities or options depend on the release. For example, if you develop a script that relies on the format of the fatal error log, then this script might not work as expected if the format of the log file changes in a future release.
In addition to the tools described in this document, you can develop custom tools using the APIs that are provided with the JDK release. For more information on developing your own tools for troubleshooting, see "Custom Diagnostic Tools".
The tools and options are divided into several categories, depending on the type of problem that you are troubleshooting. Certain tools and options might fall into more than one category.
Post-mortem diagnostics. These tools and options can be used to diagnose a problem after an application has crashed. See "Tools and Options for Post-Mortem Diagnostics".
Hung processes. These tools can be used to investigate a hung or deadlocked process. See "Tools and Options for Hung Processes".
Monitoring. These tools can be used to monitor a running application. See "Tools and Options for Monitoring".
Other. These tools and options can be used to help diagnose other issues. See "Other Tools, Options, Variables, and Properties".
Operating system tools. These tools are provided by the specific operating systems. See "Native Operating System Tools".
The table in 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.
Table 1-1 Tools and Options for Post-Mortem Diagnostics
| 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 "Fatal Error Log". |
|
|
This command-line option specifies the generation of a heap dump when the VM detects a native out-of-memory error. See "The |
|
|
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 "The |
|
|
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, |
|
Other |
Several other |
|
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). |
|
|
Debugger support includes an |
|
|
This utility provides a convenient means to browse the object topology in a heap dump. See "The |
|
(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 |
|
(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 |
|
(Solaris OS and Linux only) |
The Serviceability Agent Debug Daemon ( |
|
|
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 "The |
|
Native tools |
Each operating system has native tools and utilities that can be used for post-mortem diagnosis. See "Native Operating System Tools". |
The table in this section summarizes the options and tools that can help in scenarios involving a hung or deadlocked process. These tools do not require any special options to start the application.
Table 1-2 Tools and Options for Hung Processes
| Tool or Option | Description and Usage |
|---|---|
|
Ctrl-Break handler (Control+\ or |
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 "Control+Break Handler". |
|
|
Debugger support includes attaching connectors, which allow |
|
|
This utility provides a convenient means to browse the object topology in a heap dump. See "The |
|
|
This utility can obtain configuration information from a Java process. See "The |
|
|
This utility can obtain memory map information, including a heap histogram, from a Java process. On Solaris OS and Linux, the |
|
(Solaris OS and Linux only) |
The Serviceability Agent Debug Daemon ( |
|
|
This utility can obtain Java and native stack information from a Java process. On Solaris OS and Linux the |
|
Native tools |
Each operating system has native tools and utilities that can be useful in hang or deadlock situations. See "Native Operating System Tools". |
The tools listed in the table below are designed for monitoring applications that are running at the time.
Table 1-3 Tools and Options for Monitoring
| 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 "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 "JConsole". |
|
|
This utility can obtain memory map information, including a heap histogram, from a Java process, a core file, or a remote debug server. See "The |
|
|
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 |
|
|
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 "The |
|
|
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 "The |
|
|
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 "The |
|
|
This utility provides a graphical view of the garbage collection system. As with |
|
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 "Native Operating System Tools". |
In addition to the tools that are designed for specific types of problems, the tools, options, variables, and properties listed in the table below can help in diagnosing other issues.
Table 1-4 General Troubleshooting Tools and Options
| 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 "HPROF". |
|
|
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 "The |
|
|
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 "The |
|
|
This utility is a command-line script shell, which supports both interactive and batch-mode script execution. See "The |
|
Sun Studio |
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 |
|
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. |
|
|
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 "The |
|
|
This option enables logging of class loading and unloading. See "The |
|
|
This option enables logging of garbage collection information. See "The |
|
|
This option enables logging of JNI. See "The |
|
|
This environment variable allows you to specify the initialization of tools, specifically the launching of native or Java programming language agents using the |
|
|
This system property controls whether the security checks in the JRE of the Java print trace messages during execution. See "The |
