JavaScript interface to Hotspot Serviceability Agent

Serviceability Agent (SA) provides Java API and tools to diagnose HotSpot Virtual Machine and Java apps running on it. SA is a snapshot debugger -- can be used to observe state of a frozen java process or java core dump.

Existing SA APIs

There are two application programmer interfaces (APIs) for SA:

1. Private java API

This tries to mimic hotspot VM's internal C++ classes and methods. Because VM data structures are a moving target, this API can never be 'stable'! Besides, to use SA's private API knowledge of HotSpot code base is essential.

2. SA-JDI -- Java Debugger Interface read-only subset API

This is read-only subset of JDI (Java Debugger Interface) This is a standardized interface to get java level state of a java process or java core dump. While this interface is useful, this misses parts of java level state from target process or core such as

• heap walking interface -- only objects traceable to static variables (of classes) and local variables of stack frames can be accessed.
• re-constructing .class from debuggee are missing.
• re-constructing object mirrors for Java objects of the debuggee.

SA Scripting interface

Traditionally, platform debuggers such as dbx, gdb and Solaris mdb (Module Debugger), provide a scripting language interface. Scripting language interface provides easy-to-use, dynamically typed interface to access data structures from debuggee. dbx and mdb even allow user to write C/C++ modules to extend the scripting language commands.

SA provides SOQL - Simple Object Query Language -- a SQL-like query language to access Java heap as an object database. SA's main GUI (HSDB) also exposes scripting interface of underlying debugger such as dbx, windbg. But to use this interface, user has to learn scripting interface of multiple debugger back-ends such as dbx, windbg. And these scripting interfaces are 'raw' in the sense that no java state is exposed -- only C/C++ state of VM is exposed. Higher level SA services are not available through scripting interface.

jsdb -- JavaScript Debugger attempts to provide JavaScript interface to SA. jsdb provides

• high-level hotspot (and SA) independent scripting interface
• low-level SA-aware scripting interface.

High level interface (Java State)

jdsb globals

jvm object

jvm object supports the following read-only properties.

heap object

heap object represents Java heap of the debuggee VM

Accessing Java objects and arrays in script

From a given Java object, we can access all fields of the Java object by usual '.' operator. i.e., if you got a Java object called 'o' of type java.lang.Thread from debuggee, you can access 'stackSize' field by o.stackSize syntax. Similarly, length of Java array objects can be accessed by length property. And array indexing follows usual syntax. i.e., n'th element of array 'a' is accessed by a[n].

jvm.threads array

This is a JavaScript array of Java threads of the debuggee. As usual, 'length' property tells the number of threads and individual threads may be accessed by index operator -- i.e, jvm.threads[0] returns the first thread.

thread object

In addition to the fields of java.lang.Thread (or subclass) fields, thread objects have two additional properties.

• frames -- array of stack frame objects
• monitors -- array of monitor objects owned by the thread

stack frame object

method object

method object represents a Java method of debuggee

class object

A class object represents loaded Java class in debuggee VM. This represents java.lang.Class instance in the debuggee. This is type of return value of classof global function. Also, method.holder property and field.holder are of this type.

field object

field represents a static or instance field of some class in debuggee

Initialization Script

jsdb engine looks for initialization script file named jsdb.js in user's home directory. If found, it loads just after attaching to debuggee but before printing prompt for user's input. User can assume that s/he can access debuggee VM state during initialization script.

Sample scripts

Script to print system properties of JVM

jvm.sysProps.toString()

Script to print JVM command line flags

jvm.flags.toString()

Script to print class-wise histogram of objects

// associate array to hold histogram
var histo;
function func(obj) {
    var classname = classof(obj).name;
    if (histo[classname] == undefined) {
       // first time we are visiting this class type
       histo[classname] = 1;
    } else {
       histo[classname]++; 
    }
}

// iterate through java heap calling 'func' for each object
jvm.heap.forEachObject(func);

// print the histogram
for (i in histo) {
   println('number of instances of ', i, ' = ', histo[i]);
}

Script to print stack trace of all Java threads

function printStackTrace(t) {
    println(t.name);
    println('');
    for (i in t.frames) {
       println(t.frames[i]);
    }
    println('');
}

// walk through the list of threads and call printStackTrace
// for each thread
for (o in jvm.threads) {
    printStackTrace(jvm.threads[o]);
}

Script to re-construct .class files for all non-bootstrap classes

function dump(cl) {
   if (!cl.isArrayClass  && cl.classLoader != null) { 
      // not an array class and a non-bootstrap class
      // create .class files in e:\tmp dir
      dumpClass(cl, "e:\\tmp); 
   } else {
      println("skipping bootstrap class ", cl.name);
   }
}

// walk thru heap and call callback for each java.lang.Class instance
jvm.heap.forEachObject(dump, "java.lang.Class");

Script to print paths of all java.io.File's currently accessed

function printFile(f) {
   // construct a mirror java.io.File here and
   // print absolute path here
   println(mirror(f).getAbsolutePath());
}

jvm.heap.forEachObject(printFile, "java.io.File");

Script to print static fields of java.lang.Thread class

var threadClass = classof("java.lang.Thread");
for (i in threadClass.statics) {
  println(i, '=', threadClass.statics[i]);
}

Low level interface (VM State)

Low level jsdb interface works by JavaScript-to-Java (previously known as "LiveConnect") interface provided by Rhino JavaScript engine.

sapkg object

This object provides short names for SA package names. For eg. instead of writing Packages.sun.jvm.hotspot.memory, we can write sapkg.memory.

sa object

This object contains all SA singleton objects such as VM, Universe, SymbolTable, SystemDictionary, ObjectHeap, CollectedHeap, Debugger, CDebugger (if available), Interpreter, TypeDataBase and Threads. For eg. to access SymbolTable of Java debuggee, we can use sa.symbolTable. User can execute the following code to get fields of this object.

for (i in sa) {
  println(i);
}

Heap Iterators

forEachOop(callback)

calls a callback function for each Oop in Java heap

forEachOopOfKlass(callback, klass, [includeSubtypes])

calls a callback function for each Oop of a give Klass type Optinally, third argument can specify whether to include subtype Oops or not.

System Dictionary Access

forEachKlass(callback)

calls a callback function for each Klass in Java heap

forEachKlassAndLoader(callback)

calls callback with Klass and initiating loader (Oop) for System dictionary entry.

forEachPrimArrayKlass(callback)

calls callback with Klass and initiating loader (Oop) for each primitive array Klass in the system.

findInstanceKlass(name)

finds the first instance klass with given name from System dictionary

Thread, Frame Iterators

forEachJavaThread(callback)

calls callback for each Java Thread

forEachFrame(javaThread, callback)

calls callback for each Frame of a given JavaThread

forEachVFrame(javaThread, callback)

calls callback for each JavaVFrame of a given JavaThread

forEachThread(callback)

calls callback for each (native) ThreadProxy (obtained by CDebugger.getThreadList)

forEachCFrame(threadProxy, callback)

calls callback for each CFrame of a given ThreadProxy object

Code blobs, Interpreter codelets

forEachCodeBlob(callback)

calls callback with each code blob in code cache

findCodeBlob(address)

finds the code blob, if any, that contains the given address. Returns null, on failure.

findNMethod(address)

finds the NMethod that contains given address.

pcDescAt(addr)

returns PCDesc at given address or null.

forEachInterpCodelet(callbacl)

calls callback with each Interpreter codelet

VM structs, constants

forEachType(callback)

calls callback for each Type in VM's type database

forEachVMIntConst(callback)

calls callback for each named integer constant. passes name as argument.

forEachVMLongConst(callback)

calls callback for each named long constant. passes name as argument.

findVMType(name)

finds a VM type by name. returns null if no known Type of given name exists in type database.

findVMIntConst(name)

finds an integer constant in type data base by name.

findVMLongConst(name)

finds an long constant in type data base by name.

vmTypeof(addr)

returns VM type of object at 'addr' if any. Else, returns null.

isOfVMType(addr, type)

returns whether object at 'addr' is of VM type 'type' or not.

printVMType(type, addr)

prints 'addr' as VM object of type 'type'

printXXX(addr)

For each VM type, these functions are defined. For eg. there is printUniverse, printSystemDictionary etc. are available. Without 'addr' being passed static fields are printed. With 'addr' param being passed, instance fields are printed.

Low level debugger facilities

num2addr(number)

converts a (long) number to SA Address instance

str2addr(string)

converts a given hex string to SA Address instance

any2addr(any)

Takes a number or a string or an Address and returns an Address instance. For other types, returns 'undefined'

addr2str(addr)

converts a given Address instance to a hex string

addr2num(addr)

converts a given Address instance to a (long) number

sym2addr(library, symbol)

returns Address of a given symbol in a given library (shared object or DLL) Example: sym2addr('jvm.dll', 'JNI_CreateJavaVM')

addr2sym(addr)

Returns nearest symbol to a given address (if any). If no such symbol is found, returns the given address as a string.

readBytesAt(addr, num)

returns 'num' bytes at 'addr' as a Java byte[]

readWordsAt(addr, num)

returns 'num' words at 'addr' as a Java long[]

readCStrAt(addr)

returns 'C' String at given address

readCStrLen(addr)

returns the length of the 'C' String at given address

readRegs(threadProxy)

returns register set (of Thread Context) of a given thread specified by threadProxy. return value is an associate array having name-value pairs of registers.

regs(threadProxy)

prints register set of a given thread.

mem(addr, [num])

prints 'num' words (address size) at 'addr'. Prints nearest symbol for address, if found.

dis(addr, [num])

prints native code disassembly of 'num' bytes at given address 'addr'. Default value of 'num' is 4. This automatically detects whether the given address inside a nmethod. If so, it prints safepoint info, entry points , method signature etc. of the nmethod.

jdis(method [or addr])

prints Java bytecode disassembly for given method Oop or address of a method Oop.

nmethoddis(nmethod)

prints disassembly of given nmethod object. Note that you don't have to call this directly instead use 'dis'.

where

prints Java stack trace for all Java threads

Miscellaneous

addr2oop(addr)

converts a given address to a Oop object

oop2addr(oop)

returns address of a given Oop object

isOfVMType(addr, type)

returns whether the given 'addr' points to a (C++) VM object of specified type. type may be specified by SA Type object or string name of the type.

newVMObject(addr)

returns instance of SA object for a given address (similar to SA VirtualConstructor interface).

vmobj2addr(vmobject)

returns Address represented by a given SA VMObject

addr2vmobj(addr)

same as newVMObject(addr)

whatis(addr)

returns string description of given address (using SA FindPointer and guess type API).

isOop(addr)

returns whether a given address is a valid Oop address or not

Moving b/w jsdb low level and high level interfaces

Java objects of debuggee are represented by different script wrappers in high level interface. In the low-level interface these are instances of SA Oop class or its' subclass. To move b/w low-level and high-level interfaces the following functions may be used

oop2obj(oop)

converts a given Oop object to a high-level wrapper object

obj2oop(obj)

converts a jsdb high level wrapper to underlying Oop instance

JavaScript tips

• to know properties, functions of any object, use the script

  
  for(i in object) { println(i); }
  
  

• to view the source code of any function, just type the name of function in jsdb prompt
• to view global functions, properties, run

  
  for(i in this) { println(i); }