java/byteman docs: man stap.1 stapprobes.3stap

diff --git a/man/stap.1 b/man/stap.1
index a7ade7be4d9c4fe94e25cea5df87d49a27b40726..b5335da513fcd4ae4cfff75ae6c4aa04d5b0feec 100644 (file)
--- a/man/stap.1
+++ b/man/stap.1
@@ -597,6 +597,16 @@ below for more information.
 .BI \-\-dyninst
 Shorthand for \fI\-\-runtime=dyninst\fR.
 
+.TP
+.BI \-J "OPTION"
+For Java method probes, pass \-DOPTION to bminstall when invoking
+Byteman.
+
+.TP
+.BI \-j
+For Java method probes, pass \-Dorg.jboss.byteman.compile.to.bytecode
+to bminstall when invoking Byteman.
+
 .SH ARGUMENTS
 
 Any additional arguments on the command line are passed to the script

diff --git a/man/stapprobes.3stap b/man/stapprobes.3stap
index 8d44f2b4dc794f6118e8a0d151e92a907da46ae5..e9cc50664155881e48094c22e982ac2639026147 100644 (file)
--- a/man/stapprobes.3stap
+++ b/man/stapprobes.3stap
@@ -799,6 +799,61 @@ If systemtap was invoked with the
 options, then process probes are restricted to the process
 hierarchy associated with the target process.
 
+.SS JAVA
+Support for probing Java methods is available using Byteman as a
+backend. Byteman is an instrumentation tool from the JBoss project
+which systemtap can use to monitor invocations for a specific method
+or line in a Java program.
+.PP
+Systemtap does so by generating a Byteman script listing the probes to
+instrument and then invoking the Byteman
+.IR bminstall
+utility. A custom option "\-D OPTION" (see the Byteman documentation
+for more details) can be passed to bminstall by invoking "stap \-J
+OPTION". The systemtap option "\-j" is also provided as a shorthand for
+"\-J org.jboss.byteman.compile.to.bytecode".
+.PP
+This Java instrumentation support currently has a major limitation: java
+probes attach only to one Java process at a time; other Java processes
+beyond the first one to be observed are ignored.
+
+.PP
+The first probe type refers to Java processes by the name of the Java process:
+.SAMPLE
+java("PNAME").class("CLASSNAME").method("PATTERN")
+java("PNAME").class("CLASSNAME").method("PATTERN").return
+.ESAMPLE
+The PATTERN parameter specifies the signature of the Java method to
+probe. The signature must consist of the exact name of the method,
+followed by a bracketed list of the types of the arguments, for
+instance "myMethod(int,double,Foo)". Wildcards are not supported.
+.PP
+The probe can be set to trigger at a specific line within the method
+by appending a line number with colon, just as in other types of
+probes: "myMethod(int,double,Foo):245".
+.PP
+The CLASSNAME parameter identifies the Java class the method belongs
+to, either with or without the package qualification. By default, the
+probe only triggers on descendants of the class that do not override
+the method definition of the original class. However, CLASSNAME can
+take an optional caret prefix, as in
+.IR ^org.my.MyClass,
+which specifies that the probe should also trigger on all descendants
+of MyClass that override the original method. For instance, every method
+with signature foo(int) in program org.my.MyApp can be probed at once using
+.SAMPLE
+java("org.my.MyApp").class("^java.lang.Object").method("foo(int)")
+.ESAMPLE
+.PP
+The second probe type works analogously, but refers to Java processes by PID:
+.SAMPLE
+java(PID).class("CLASSNAME").method("PATTERN")
+java(PID).class("CLASSNAME").method("PATTERN").return
+.ESAMPLE
+(PIDs for an already running process can be obtained using the
+.IR jps (1)
+utility.)
+
 .SS PROCFS
 
 These probe points allow procfs "files" in