Summary

Provide a jcmd "VM.inspect" to provide detailed JVM object information. Given an address, show the detailed fields in a Java heap object, or details of other objects known to the JVM.

Problem

The JVM can natively describe a Java Object in detail. This can be accessed by attaching a native debugger, and is used in hs_err reporting, but should be more accessible and available on demand.

Solution

The jcmd "VM.inspect" should be introduced.

Adding a jcmd will permit usage against a live process. That includes a process started with -XX:+ShowMessageBoxOnError which has stopped with an error. At that point, the VM has not created the hs_err fatal error log, but we can already run jcmd PID VM.info, to provide much of what would appear there, and a native debugger can be attached to discover the call stack. The new command will let us examine additional Java objects.

The jcmd will take an argument to specify an address.

jcmd VM.inspect will be enabled if -XX:+EnableVMInspectCommand is specified on the JVM command-line, or the JVM is a debug build. This guard flag is in place to make users specifically opt-in to the command being available, because it may not be possible to guarantee that it is safe to inspect the Java heap at an arbitrary address.

This additional command raises no new security concerns. As with all jcmds accessed via the Attach API, access control is based on the local user identity. There is no need for remote access to this DiagnosticCommand over JMX, so keeping it flagged as hidden means it is never in the list of dcmds available in that way.

Specification

The Diagnostic Command "VM.inspect" is added. There are no new Java APIs.

jcmd <pid> VM.inspect <address>

This is implemented by the existing os::print_location() method, which currently searches: CodeCache, Java Heap, JNI handles, Threads, stack locations, Metaspace, NMT information.

The option -verbose is recognised and provides more detail in some cases, e.g. jcmd PID VM.inspect -verbose=true 0xADDRESS

Also, the new JVM command-line option is introduced:

-XX:+EnableVMInspectCommand

This must be set to enable the command in a live product JVM, while in a debug build the flag will be true by deafult.