1============================
2'hotspot' PROBES DESCRIPTION
3============================
4
5This directory contains D scripts which demonstrate usage of 'hotspot' provider probes.
6
7The 'hotspot' provider makes available probes that can be used to track the
8lifespan of the VM, thread start and stop events, GC and memory pool
9statistics, method compilations, and monitor activity. With a startup flag,
10additional probes are enabled which can be used to monitor the running Java
11program, such as method enter and return probes, and object allocations. All
12of the hotspot probes originate in the VM library (libjvm.so), so they are
13also provided from programs which embed the VM.
14
15Many of the probes in the provider have arguments that can be examined to
16provide further details on the state of the VM. Many of these probes'
17arguments are opaque IDs which can be used to link probe firings to each
18other, however strings and other data are also provided. When string values
19are provided, they are always present as a pair: a pointer to unterminated
20modified UTF-8 data (see JVM spec: 4.4.7) , and a length value which
21indicates the extent of that data. Because the string data (even when none
22of the characters are outside the ASCII range) is not guaranteed to be
23terminated by a NULL character, it is necessary to use the length-terminated
24copyinstr() intrinsic to read the string data from the process.
25
26You can find more information about HotSpot probes here:
27http://java.sun.com/javase/6/docs/technotes/guides/vm/dtrace.html
28
29
30===========
31THE SCRIPTS
32===========
33
34The following scripts/samples which demonstrate 'hotspot' probes usage are
35available:
36
37- class_loading_stat.d
38  The script collects statistics about loaded and unloaded Java classes and
39  dump current state to stdout every N seconds.
40
41- gc_time_stat.d
42  The script measures the duration of a time spent in GC.
43  The duration is measured for every memory pool every N seconds.
44
45- hotspot_calls_tree.d
46  The script prints calls tree of fired 'hotspot' probes.
47
48- method_compile_stat.d
49  The script prints statistics about N methods with largest/smallest
50  compilation time every M seconds.
51
52- method_invocation_stat.d
53  The script collects statistics about Java method invocations.
54
55- method_invocation_stat_filter.d
56  The script collects statistics about Java method invocations.
57  You can specify package, class or method name to trace.
58
59- method_invocation_tree.d
60  The script prints tree of Java and JNI method invocations.
61
62- monitors.d
63  The script traces monitor related probes.
64
65- object_allocation_stat.d
66  The script collects statistics about N object allocations every M seconds.
67
68
69==========
70HOW TO RUN
71==========
72
73To run any D script from hotspot directory you can do either:
74
75 # dscript.d -c "java ..."
76
77 or if you don't have Solaris 10 patch which allows to specify probes that
78 don't yet exist ( Hotspot DTrace probes are defined in libjvm.so and as
79 result they could be not been yet loaded when you try to attach D script to
80 the Java process) do:
81
82 # ../helpers/dtrace_helper.d -c "java ..." dscript.d
83
84 or if your application is already running you can just simply attach
85 the D script like:
86
87 # dscript.d -p JAVA_PID
88