============================

'hotspot' PROBES DESCRIPTION

============================

This directory contains D scripts which demonstrate usage of 'hotspot' provider probes.

The 'hotspot' provider makes available probes that can be used to track the

lifespan of the VM, thread start and stop events, GC and memory pool

statistics, method compilations, and monitor activity. With a startup flag,

additional probes are enabled which can be used to monitor the running Java

program, such as method enter and return probes, and object allocations. All

of the hotspot probes originate in the VM library (libjvm.so), so they are

also provided from programs which embed the VM.

Many of the probes in the provider have arguments that can be examined to

provide further details on the state of the VM. Many of these probes'

arguments are opaque IDs which can be used to link probe firings to each

other, however strings and other data are also provided. When string values

are provided, they are always present as a pair: a pointer to unterminated

modified UTF-8 data (see JVM spec: 4.4.7) , and a length value which

indicates the extent of that data. Because the string data (even when none

of the characters are outside the ASCII range) is not guaranteed to be

terminated by a NULL character, it is necessary to use the length-terminated

copyinstr() intrinsic to read the string data from the process.

You can find more information about HotSpot probes here:

http://java.sun.com/javase/6/docs/technotes/guides/vm/dtrace.html

===========

THE SCRIPTS

===========

The following scripts/samples which demonstrate 'hotspot' probes usage are

available:

- class_loading_stat.d 

  The script collects statistics about loaded and unloaded Java classes and

  dump current state to stdout every N seconds.

- gc_time_stat.d

  The script measures the duration of a time spent in GC.

  The duration is measured for every memory pool every N seconds.

- hotspot_calls_tree.d

  The script prints calls tree of fired 'hotspot' probes.

- method_compile_stat.d

  The script prints statistics about N methods with largest/smallest

  compilation time every M seconds.

- method_invocation_stat.d

  The script collects statistics about Java method invocations.

- method_invocation_stat_filter.d

  The script collects statistics about Java method invocations.

  You can specify package, class or method name to trace.

- method_invocation_tree.d

  The script prints tree of Java and JNI method invocations.

- monitors.d

  The script traces monitor related probes.

- object_allocation_stat.d

  The script collects statistics about N object allocations every M seconds.

==========

HOW TO RUN

==========

To run any D script from hotspot directory you can do either:

 # dscript.d -c "java ..."

 or if you don't have Solaris 10 patch which allows to specify probes that

 don't yet exist ( Hotspot DTrace probes are defined in libjvm.so and as

 result they could be not been yet loaded when you try to attach D script to

 the Java process) do:

 # ../helpers/dtrace_helper.d -c "java ..." dscript.d

 or if your application is already running you can just simply attach

 the D script like:

 # dscript.d -p JAVA_PID