Java Platform, Standard Edition Troubleshooting Guide
Next

---

Contents

Title and Copyright Information

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 Permanent Generation 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

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 Hardware Details
  • 17.3.2 Operating System Details
  • 17.3.3 Java SE Version
  • 17.3.4 Command-Line Options
  • 17.3.5 Environment Variables
  • 17.3.6 Fatal Error Log
  • 17.3.7 Core or Crash Dump
  • 17.3.8 Detailed Description of the Problem
  • 17.3.9 Logs and Traces
  • 17.3.10 Results from Troubleshooting Steps
• 17.4 Collect Core Dumps
  • 17.4.1 Collect Core Dumps on Oracle Solaris
  • 17.4.2 Collect Core Dumps on Linux
  • 17.4.3 Reasons for Not Getting a Core File
  • 17.4.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

---