Mark Wielaard wrote:
> On Fri, 2009-12-18 at 10:20 +0000, Andrew Haley wrote:
>> jon.vanalten at redhat.com wrote:
>>
>>> I've added a small tapset which builds on the hotspot.stp and
>>> hotspot_jni.stp to help keep track of java/native threads, and a few
>>> example systemtap scripts that demo these tapsets. I'd like them to
>>> go out in the next release, if people think they are potentially
>>> useful (even if only as demonstration for how to make use of the
>>> other tapsets). Diff attached. Comments?
>> What does it do? How do we use it? I'd love to use SystemTap but I
>> fear I'd have to spend a week reading docs before I could do anything.
>
> Inside the big patch there was a README. I have added it below. Could
> you go over that and tell us if that is enough of an (practical)
> introduction to using Systemtap with java?
Well, it starts with
> ++These are some examples of systemtap scripts that demonstrate the use of some
> ++of the probes available in the Hotspot JVM and JNI code. For more information
> ++about systemtap, see:
> ++
> ++ http://sourceware.org/systemtap/index.html
> ++
> ++This README assumes that the reader is familiar with, or will use the above
> ++URL to become familiar with, how to run systemtap scripts in the general case.
> We might think it is all obvious, but I am sure that for someone
> that has never used it there are some things we forget to mention.
A document that begins with "go and read some other document" isn't
going to encourage a Java programmer. Especially when that document
starts with "how to probe your kernel". This is going to turn a Java
programmer off straight away.
How about we assume that the user does *not* want to learn about
SystemTap in the general case, but instead wants to solve a simple
Java problem. They certainly don't know about kernels, system
tracing, ect, ect.
> It might be good to have a minimal concrete example in the README, so
> someone can just step in directly. The current README only gives
> abstract examples.
Definitely, yes. A page along the lines of "I had this problem and
I solved it with SystemTap. This is how I did it..."
> Maybe something like:
>
> [Make sure systemtap is installed and setup for your user account.]
>
> To show when threads are started and stopped go into the
> j2sdk-image directory and do:
> $ stap -I tapset -e \
> 'probe hotspot.thread_* { printf("%s: %s %s\n",
> ctime(gettimeofday_s()),
> name, thread_name) }' \
> -c 'bin/java -classpath ~/src/tests Hello'
>
> This uses the tapsets in the directory given by -I tapset,
> it will execute (-e) the given stap script, where the probes
> will trigger for the given program (-c). The script sets up
> a handler on all hotspot.thread_* probes (start and stop). The
> handler (between { and }) prints the time (gettimeofday_s) in
> human readable form (ctime), the name of the probe and the name
> of the thread:
>
> Fri Dec 18 13:03:39 2009: thread_start Reference Handler
> Fri Dec 18 13:03:39 2009: thread_start Finalizer
> Fri Dec 18 13:03:39 2009: thread_start Signal Dispatcher
> Fri Dec 18 13:03:39 2009: thread_start CompilerThread0
> Fri Dec 18 13:03:39 2009: thread_start CompilerThread1
> Fri Dec 18 13:03:39 2009: thread_start Low Memory Detector
> Fri Dec 18 13:03:40 2009: thread_start Thread-0
> Fri Dec 18 13:03:40 2009: thread_stop Thread-0
> [...]
>
> If you already have icedtea installed systemwide you don't need to
> add the -I and can just invoke java (the classpath and the Hello
> class are just examples that you can replace with any java program
> you want to inspect).
>
> Would that be a simple/easy introduction to the rest of the scripts and
> using systemtap/java? Should we instead of a handwritten example use one
> of the actual example scripts Jon has added?
The best way, I think, is to assume that icedtea is installed in the
usual place. Assume that the user doesn't know about SystemTap.
Don't use jargon words like "tapset": the reader doesn't want to know
what one is. Just tell the user where to put the files they need, and
let them play. Then, when they learn how truly cool StsremTap is they
will ask "OK, how do I write my own scripts, then?"
The key is to present the ordinary Java programmer -- whatever one of
those is -- with something cool that demonstrates instant useful
results without requiring them to go away and study.
Andrew.