Documentation Contents
Java Platform, Standard Edition Troubleshooting Guide
Next
Contents
Preface
Audience
Documentation Accessibility
Related Documents
Conventions
Part I General Java Troubleshooting
1
Prepare Java for Troubleshooting
1.1
Set Up Java for Troubleshooting
1.2
Enable Options/Flags for JVM Troubleshooting
1.3
Gather Relevant Data
1.3.1
Make a Java Application Easier to Debug
2
Diagnostic Tools
2.1
Diagnostic Tools Overview
2.2
Java Mission Control
2.2.1
Troubleshoot with Java Mission Control
2.3
What Are Java Flight Recordings
2.3.1
Types of Recordings
2.4
How to Produce a Flight Recording
2.4.1
Use Java Mission Control to Produce a Flight Recording
2.4.2
Use Startup Flags at the Command Line to Produce a Flight Recording
2.4.3
Use Triggers for Automatic Recordings
2.5
Inspect a Flight Recording
2.5.1
How to Get a Sample JFR to Inspect
2.5.2
Range Navigator
2.5.3
General Tab
2.5.4
Memory Tab
2.5.5
Code Tab
2.5.6
Threads Tab
2.5.7
I/O Tab
2.5.8
System Tab
2.5.9
Events Tab
2.6
The jcmd Utility
2.6.1
Useful Commands for jcmd Utility
2.6.2
Troubleshoot with jcmd Utility
2.7
Native Memory Tracking
2.7.1
Use NMT to Detect a Memory Leak
2.7.2
How to Monitor VM Internal Memory
2.8
HPROF
2.8.1
Troubleshoot with HPROF Tool
2.8.2
Heap Allocation Profile heap=sites
2.8.3
Heap Dump Profile heap=dump
2.8.4
CPU Usage Sampling Profile cpu=samples
2.8.5
CPU Usage Times Profile cpu=times
2.9
JConsole
2.9.1
Troubleshoot with JConsole Tool
2.9.2
Monitor Local and Remote Applications with JConsole
2.10
Java VisualVM
2.10.1
Troubleshoot with Java VisualVM
2.11
The jdb Utility
2.11.1
Troubleshoot with jdb Utility
2.11.2
Attach a Process
2.11.3
Attach to a Core File on the Same Machine
2.11.4
Attach to a Core File or a Hung Process from a Different Machine
2.12
The jhat Utility
2.12.1
Troubleshoot with jhat Utility
2.12.2
Standard Queries
2.12.3
Custom Queries
2.12.4
Heap Analysis Hints
2.13
The jinfo Utility
2.13.1
Troubleshooting with jinfo Utility
2.14
The jmap Utility
2.14.1
Heap Configuration and Usage
2.14.2
Heap Histogram
2.14.3
Class Loader Statistics
2.15
The jps Utility
2.16
The jstack Utility
2.16.1
Troubleshoot with jstack Utility
2.16.2
Force a Stack Dump
2.16.3
Stack Trace from a Core Dump
2.16.4
Mixed Stack
2.17
The jstat Utility
2.18
The visualgc Tool
2.19
Control+Break Handler
2.19.1
Thread Dump
2.19.2
Detect Deadlocks
2.19.3
Heap Summary
2.20
Native Operating System Tools
2.20.1
DTrace Tool
2.20.2
Probe Providers in Java HotSpot VM
2.20.3
Improvements to pmap Tool
2.20.4
Improvements to pstack Tool
2.21
Custom Diagnostic Tools
2.21.1
Java Platform Debugger Architecture
NMT Memory Categories
Postmortem Diagnostics Tools
Hung Processes Tools
Monitoring Tools
Other Tools, Options, Variables and Properties
The java.lang.management Package
The java.lang.instrument Package
The java.lang.Thread Class
JVM Tool Interface
The jrunscript Utility
The jsadebugd Daemon
The jstatd Daemon
Thread States for a Thread Dump
Troubleshooting Tools Based on Operating System
3
Troubleshoot Memory Leaks
3.1
Debug a Memory Leak Using Java Flight Recorder
3.1.1
Detect a Memory Leak
3.1.2
Find the Leaking Class
3.1.3
Find the Leak
3.2
Understand the OutOfMemoryError Exception
3.3
Troubleshoot a Crash Instead of OutOfMemoryError
3.4
Diagnose Leaks in Java Language Code
3.4.1
Create a Heap Dump
3.4.2
Obtain a Heap Histogram
3.4.3
Monitor the Objects Pending Finalization
3.5
Diagnose Leaks in Native Code
3.5.1
Track All Memory Allocation and Free Calls
3.5.2
Track All Memory Allocations in JNI Library
3.5.3
Track Memory Allocation with Operating System Support
3.5.4
Find Leaks with dbx Debugger
3.5.5
Find Leaks with libumem Tool
4
Troubleshoot Performance Issues Using JFR
4.1
JFR Overhead
4.2
Find Bottlenecks
4.3
Garbage Collection Performance
4.4
Synchronization Performance
4.5
I/O Performance
4.6
Code Execution Performance
Part II Debug JVM Issues
5
Troubleshoot System Crashes
5.1
Determine Where the Crash Occurred
5.1.1
Crash in Native Code
5.1.2
Crash in Compiled Code
5.1.3
Crash in HotSpot Compiler Thread
5.1.4
Crash in VM Thread
5.1.5
Crash Due to Stack Overflow
5.2
Find a Workaround
5.2.1
Working Around Crashes in the HotSpot Compiler Thread or Compiled Code
5.2.2
Working Around Crashes during Garbage Collection
5.2.3
Working Around Crashes Caused by Class Data Sharing
5.3
Microsoft Visual C++ Version Considerations
5.3.1 JNI Libraries Compiled with Different Microsoft Visual Studio Version
5.3.2 Dependencies on Older Microsoft Visual Studio Libraries
6
Troubleshoot Process Hangs and Loops
6.1
Diagnose a Loop Process
6.2
Diagnose a Hung Process
6.2.1
Deadlock Detected
6.2.2
Deadlock Not Detected
6.2.3
No Thread Dump
6.3
Oracle Solaris 8 Thread Library
7
Handle Signals and Exceptions
7.1
Handle Signals on Oracle Solaris and Linux
7.2
Handle Exceptions on Windows
7.3
Signal Chaining
7.4
Handle Exceptions using Java HotSpot VM
Console Handlers
Signals Used in Oracle Solaris and Linux
Part III Debug Core Library Issues
8
Time Zone Settings in the JRE
8.1
Native Time Zone Information and the JRE
8.1.1
Determine the Time Zone Data Version in Use
8.1.2
Troubleshoot Problems with TZupdater
8.2
Determine the Default Time Zone on Windows
8.2.1
Check the Default Time Zone JRE Reports
8.2.2
Determine the Setting in the Control Panel
8.2.3
Check for Automatic Daylight Saving Time Adjustment
8.2.4
Set the Default Time Zone in the Control Panel
8.2.5
Check -Duser.timezone System Property
8.2.6
Special Tools in Windows 7
8.2.7
JRE Internal Representation of Time Zone Mappings
Part IV Debug Client Issues
9
Introduction to Client Issues
9.1
Java SE Desktop Technologies
9.2
General Steps to Troubleshoot an Issue
9.3
Identify the Type of Issue
9.3.1
Java Client Crashes
9.3.2
Performance Problems
9.3.3
Behavior Problems
9.4
Basic Tools
9.5
JDWP
10
AWT
10.1
Debug Tips for AWT
10.2
Layout Manager Issues
10.3
Key Events
10.4
Modality Issues
10.5
Memory Leaks
10.6
AWT Crashes
10.7
Focus Events
10.7.1
How to Trace Focus Events
10.7.2
Native Focus System
10.7.3
Focus System in Java Plug-in
10.7.4
Focus Models Supported by X Window Managers
10.7.5
Miscellaneous Problems with Focus
10.8
Data Transfer
10.8.1
Debug Drag and Drop Applications
10.8.2
Frequent Issues with Data Transfer
10.9
Other Issues
10.9.1
Splash Screen Issues
10.9.2
Tray Icon Issues
10.9.3
Popup Menu Issues
10.9.4
Background/Foreground Color Inheritance
10.9.5
AWT Panel Size Restriction
10.9.6
Hangs during Debugging Popup Menus and Similar Components on X11
10.9.7
Window.toFront()/toBack() Behavior on X11
10.10
Heavyweight/Lightweight Components Mix
11
Java 2D Pipeline Rendering and Properties
11.1
Oracle Solaris and Linux: X11 Pipeline
11.1.1
X11 Pipeline Pixmaps Properties
11.1.2
X11 Pipeline MIT Shared Memory Extension
11.1.3
Oracle Solaris on SPARC: DGA Support
11.1.4
Oracle Solaris on SPARC - Change Java 2D Default Visual
11.2
Windows OS - DirectDraw/GDI Pipeline
11.3
Windows OS - Direct3D Pipeline in Full-Screen Mode
11.4
OpenGL Pipeline in Oracle Solaris, Linux and Windows
11.4.1
Enable OpenGL Pipeline
11.4.2
Minimum Requirements
11.4.3
Diagnose Startup Issues
11.4.4
Diagnose Rendering and Performance Issues
Latest OpenGL Drivers
12
Java 2D
12.1
Generic Performance Issues
12.1.1
Hardware Accelerated Rendering Primitives
12.1.2
Primitive Tracing to Detect and Avoid Non-accelerated Rendering
12.1.3
Causes of Poor Rendering Performance
12.1.4
Improve Performance of Software-only Rendering
12.2
Text Related Issues
12.2.1
Application Crash During Text Rendering
12.2.2
Differences in Text Appearance
12.2.3
Metrics
12.3
Java 2D Printing
13
Swing
13.1
General Debug Tips for Swing
13.2
Specific Debug Tips for Swing
13.2.1
Incorrect Threading
13.2.2
JComponent Children Overlap
13.2.3
Display Update
13.2.4
Model Change
13.2.5
Add or Remove Components
13.2.6
Opaque Override
13.2.7
Permanent Changes to Graphics
13.2.8
Custom Painting and Double Buffering
13.2.9
Opaque Content Pane
13.2.10
Renderer Call for Each Cell Performance
13.2.11
Possible Leaks
13.2.12
Mix Heavywight and Lightweight Components
13.2.13
Use Synth
13.2.14
Track Activity on Event Dispatch Thread
13.2.15
Specify Default Layout Manager
13.2.16
Listener Object Dispatched to Incorrect Component
13.2.17
Add a Component to Content Pane
13.2.18
Drag and Drop Support
13.2.19
One Parent for a Component
13.2.20
JFileChooser Issues with Windows Shortcuts
14
Internationalization
14.1
Troubleshoot Internationalization and Localization
15
Java Sound
15.1
Troubleshoot Java Sound Issues
16
Applets and Java Web Start Applications
16.1
Configuration Problems
16.1.1
Validation
16.1.2
Common Configuration Problems
16.1.3
Manage Java Runtime
16.1.4
Pass Parameters to the JRE
16.1.5
Java Deployment Home
16.1.6
Deployment Tracing
16.1.7
Deployment Cache
16.1.8
Network Configuration
16.2
Troubleshoot Applets
16.2.1
Plugin Cheat Sheet for Applet Start
16.2.2
Browser or Java Process Crash
16.2.3
Unresponsive Web page
16.3
Avoid Security Dialogs
16.3.1
Signed Applications
16.3.2
Mixed Code Issues
16.4
Development Tips
Part V Submit Bug Reports
17
Submit a Bug Report
17.1
Check for Fixes in Update Releases
17.2
Prepare to Submit a Bug Report
17.3
Collect Data for a Bug Report
17.3.1
Detailed Description of the Problem
17.3.2
Hardware Details
17.3.3
Operating System Details
17.3.4
Java SE Version
17.3.5
Command-Line Options
17.3.6
Environment Variables
17.3.7
Fatal Error Log
17.3.8
Core or Crash Dump
17.3.9
Logs and Traces
17.4
Report a Bug
17.5
Collect Core Dumps
17.5.1
Collect Core Dumps on Oracle Solaris
17.5.2
Collect Core Dumps on Linux
17.5.3
Reasons for Not Getting a Core File
17.5.4
Collect Crash Dumps on Windows
Part VI Appendix
A
Fatal Error Log
Location of Fatal Error Log
Description of Fatal Error Log
Header Format
Thread Section Format
Process Section Format
System Section Format
B
Java 2D Properties
Properties on Oracle Solaris and Linux
Properties on Windows
C
Environment Variables and System Properties
The
JAVA_HOME
Environment Variable
The
JAVA_TOOL_OPTIONS
Environment Variable
The
java.security.debug
System Property
D
Command-Line Options
Java HotSpot VM Command-Line Options
Other Command-Line Options
E
Summary of Tools in This Release
Next
