Quick Troubleshooting Tips on Solaris OS and Linux for Java SE 5.0

This "Quick Start Guide" gives you some quick tips for troubleshooting. The subsections list some typical functions that can help you in troubleshooting, including one or more ways to get the information or perform the action.

These tips are organized as follows:

Hung, Deadlocked, or Looping Process
Post-mortem Diagnostics, Memory Leaks
Monitoring
Actions on a Remote Debug Server
Other Functions

Hung, Deadlocked, or Looping Process

  • Print thread stack for all Java threads:
    • Control-\
    • kill -QUIT pid
    • jstack pid
  • Detect deadlocks:
    • Print information on deadlocked threads: Control-\
    • Print list of concurrent locks owned by each thread: -XX:+PrintConcurrentLocks set, then Control-\
  • Get a heap histogram for a process:
    • Start Java process with -XX:+PrintClassHistogram, then Control-\
    • jmap -histo pid
  • Print shared object mappings for a process:
    • jmap pid
  • Print heap summary for a process:
    • Control-\
    • jmap -heap pid
  • Attach the command-line debugger to a process:
    • jdb -connect sun.jvm.hotspot.jdi.SAPIDAttachingConnector:pid= pid
  • Create a heap dump:
    • Start the application with HPROF enabled: java -agentlib:hprof=file= file ,format=b application; on Control-\, VM generates a heap dump.
    • Start VM with -XX:+HeapDumpOnCtrlBreak; on Ctrl-\, VM generates a heap dump. (Introduced in Java SE 5.0 update 14.)

Post-mortem Diagnostics, Memory Leaks

  • Examine the fatal error log file. Default file name is hs_err_pid pid .log in the working-directory.
  • Create a heap dump:
    • Start the application with HPROF enabled: java -agentlib:hprof=file= file ,format=b application; on Control-\, VM generates a heap dump.
    • Start the application with HPROF enabled: java -agentlib:hprof=heap=dump application
    • Start VM with -XX:+HeapDumpOnOutOfMemoryError; if OutOfMemoryError is thrown, VM generates a heap dump. (Introduced in Java SE 5.0 update 7.)
  • Browse Java heap dump:
    Heap Analysis Tool (HAT)
  • Get a heap histogram for a process:
    • Start Java process with -XX:+PrintClassHistogram, then Control-\
    • jmap -histo pid
  • Get a heap histogram from a core file:
    • jmap -histo corefile
  • Print shared object mappings from a core file:
    • jmap corefile
  • Print heap summary from a core file:
    • jmap -heap corefile
  • Print Java configuration information from a core file:
    • jinfo corefile
  • Print thread trace from a core file:
    • jstack corefile
  • Attach the command-line debugger to a core file on the same machine:
    • jdb -connect sun.jvm.hotspot.jdi.SACoreAttachingConnector:javaExecutable= path ,core= corefile
  • Attach the command-line debugger to a core file on a different machine:
    • On the machine with the core file: jsadebugd path corefile
      and on the machine with the debugger: jdb -connect sun.jvm.hotspot.jdi.SADebugServerAttachingConnector:debugServerName= machine
  • libumem can be used to debug memory leaks.

Monitoring

Note: The vmID argument for the jstat command is the virtual machine identifier. See the jstat man page for a detailed explanation.

  • Print statistics on the class loader:
    • jstat -class vmID
  • Print statistics on the compiler:
    • Compiler behavior: jstat -compiler vmID
    • Compilation method statistics: jstat -printcompilation vmID
  • Print statistics on garbage collection:
    • Summary of statistics: jstat -gcutil vmID
    • Summary of statistics, with causes: jstat -gccause vmID
    • Behavior of the gc heap: jstat -gc vmID
    • Capacities of all the generations: jstat -gccapacity vmID
    • Behavior of the new generation: jstat -gcnew vmID
    • Capacity of the new generation: jstat -gcnewcapacity vmID
    • Behavior of the old and permanent generations: jstat -gcold vmID
    • Capacity of the old generation: jstat -gcoldcapacity vmID
    • Capacity of the permanent generation: jstat -gcpermcapacity vmID
  • Monitor objects awaiting finalization:
    • JConsole tool, Memory tab
    • getObjectPendingFinalizationCount method in java.lang.management.MemoryMXBean class
  • Monitor memory:
    • Heap allocation profiles via HPROF: java -agentlib:hprof=heap=sites
    • JConsole tool, Memory tab
    • Control-\ prints generation information.
  • Monitor CPU usage:
    • By thread stack: java -agentlib:hprof=cpu=samples application
    • By method: java -agentlib:hprof=cpu=times application
    • JConsole tool, Overview and VM Summary tabs
  • Monitor thread activity:
    • JConsole tool, Threads tab
  • Monitor class activity:
    • JConsole tool, Classes tab

Actions on a Remote Debug Server

First, attach the debug daemon jsadebugd, then execute the command:

  • Print shared object mappings: jmap hostID
  • Print heap summary : jmap -heap hostID
  • Print thread trace : jstack hostID
  • Print Java configuration information: jinfo hostID

Other Functions

  • Interface with the instrumented Java virtual machines:
    • Monitor for the creation and termination of instrumented VMs: jstatd daemon
    • List the instrumented VMs: jps
    • Provide interface between remote monitoring tools and local VMs: jstatd daemon
    • Request garbage collection: JConsole tool, Memory tab
  • Print Java configuration information from a running process:
    • jinfo pid
  • Print command-line flags passed to the VM:
    • jinfo -flags
  • Print Java system properties:
    • jinfo -sysprops
  • Print statistics of permanent generation of Java heap, by class loader:
    • jmap -permstat
  • Report on monitor contention.
    • java -agentlib:hprof=monitor=y application
  • Interface dynamically with an MBean, via JConsole tool, MBean tab:
    • Show tree structure.
    • Set an attribute value.
    • Invoke an operation.
    • Subscribe to notification.
  • Run interactive command-line debugger:
    • Launch a new VM for the class: jdb class
    • Attach debugger to a running VM: jdb -attach address