Interactive mode introduction

[David Smith <dsmith at redhat dot com>]

In the upcoming systemtap release, you'll see the following item in the
NEWS file:

  The new experimental "interactive" mode, specified by "stap -i",
  drops you into a command-line prompt where you can build up a script,
  run it, edit it, run it again, etc. Type "help" for a list of
  commands.

Here's what this looks like in practice. Note that I'm putting comments
between sections of the continuous interactive session below, but in
reality you never leave interactive mode.

First, let's start up systemtap's interactive mode and get a list of
commands we can run:

====
# stap -i
stap> help
List of commands:

add                   -- Add a global, probe, or function.
delete LINE_NUM_RANGE -- Delete script line(s) by line numbers. To
delete a single line, specify LINE_NUM_RANGE as "10". To delete a range
of lines, specify LINE_NUM_RANGE as "12-20". To delete the entire
script, give no argument.
list                  -- Display the current script.
edit                  -- Edit the current script. Uses EDITOR
environment variable contents as editor (or ex as default).
load FILE             -- Load a script from a file into the current session.
save FILE             -- Save a script to a file from the current session.
run                   -- Run the current script.
set OPTION VALUE      -- Set option value. Supported options are:
    keep_tmpdir       -- Keep temporary directory.
    last_pass         -- Stop after pass NUM 1-5.
    verbose           -- Add verbosity to all passes.
    guru_mode         -- Guru mode.
    suppress_warnings -- Suppress warnings.
    panic_warnings    -- Turn warnings into errors.
    timing            -- Collect probe timing information.
    unoptimized       -- Unoptimized translation.
    target_pid        -- Sets target() to PID.
    cmd               -- Start the probes, run CMD, and exit when it
finishes.
    auto_analyze      -- Automatically analyze the current script after
changes.
show OPTION           -- Show option value.
help                  -- Print this command list.
quit                  -- Quit systemtap.
====

Let's add a global to our script. Note that (by default) after
every command that modifies the current script, the script is
analyzed (by running it through pass 2. To turn this behavior
off, set auto_analyze to '0'.

In this case systemap rightly points out that we've got an
unused global.

====
stap> add global iter
Script analysis:
WARNING: Eliding unused variable 'iter': identifier 'iter' at <input>:1:8
 source: global iter
                ^
semantic error: no probes found

Pass 2: analysis failed.  [man error::pass2]
====

Let's add a probe that uses the global we added. If a probe or function
isn't specified on a single line, interactive mode will show you the
continuation prompt 'stap>>>' until the probe or function is complete.

====
stap> add probe timer.s(2)
stap>>> {
stap>>>     printf("timer probe, iter = %d\n", ++iter)
stap>>>     if (iter >= 3) exit()
stap>>> }
Script analysis:
# globals
iter:long
# functions
exit:unknown ()
# probes
timer.s(2) /* <- timer.s(2) */
====

Let's do some bigger work on our script. We'll use the 'edit' command,
which will pop the current script in your editor, where you can change
it. When you exit your editor, the changes will be reflected back in
systemtap.

====
stap> edit
Script analysis:
# globals
iter:long
# functions
exit:unknown ()
# probes
begin /* <- begin */
timer.s(2) /* <- timer.s(2) */
end /* <- end */
====

Let's look at our script at this point:

====
stap> list
 1: global iter
 2:
 3: probe begin
 4: {
 5:     printf("systemtap starting\n")
 6: }
 7:
 8: probe timer.s(2)
 9: {
10:     printf("timer probe, iter = %d\n", ++iter)
11:     if (iter >= 3) exit()
12: }
13:
14: probe end
15: {
16:     printf("systemtap ending\n")
17: }
====

OK, let's run the script and see how it goes.

====
stap> run
systemtap starting
timer probe, iter = 1
timer probe, iter = 2
timer probe, iter = 3
systemtap ending
====

OK, the basic script framework looks reasonable. Let's actually measure
something. I'll edit the script again and then display it so you can see
what I've done to it.

====
stap> edit
Script analysis:
# global embedded code
%{
#include <linux/uaccess.h>		/* For VERIFY_READ/VERIFY_WRITE */
#include <linux/uio.h>			/* For ITER_IOVEC */
%}
%{
#include <linux/kdev_t.h>
%}
%{
#include <linux/kernel.h>
#include <linux/nfs_fs.h>
#include <linux/uaccess.h>		/* For VERIFY_READ/VERIFY_WRITE */
%}
%{
/* For AF_INET */
#include <linux/socket.h>
%}
# globals
iter:long
reads:stats
# functions
exit:unknown ()
# probes
begin /* <- begin */
timer.s(2) /* <- timer.s(2) */
kernel.function("vfs_read@fs/read_write.c:440") /* pc=_stext+0x22dcf8 */
/* <- kernel.function("vfs_read@fs/read_write.c:440") */
end /* <- end */
stap> list
1: global iter, reads
2:
3: probe begin
4: {
5: printf("systemtap starting\n")
6: }
7:
8: probe timer.s(2)
9: {
10: printf("reads: %d\n", @count(reads))
11: if (++iter >= 3) exit()
12: }
13:
14: probe vfs.read
15: {
16: reads <<< 1
17: }
18:
19: probe end
20: {
21: printf("systemtap ending\n")
22: }
====

So, the script measures reads and every 2 seconds reports how many we've
seen.

Let's see how it works.

====
stap> run
systemtap starting
reads: 14
reads: 45
reads: 61
systemtap ending
====

OK, that looks reasonable, so let's save the script and quit.

====
stap> save vfs_reads.stp
stap> quit
====

As you can see from the brief session above, interactive mode is useful
for interactively adding, modifying, testing, etc. a systemtap script
you are working on.

So what's the current state of interactive mode? Well, it works (as you
can see from the above), but we're planning on refining it in the future
(which is why the NEWS file says it is "experimental").

If you are running the pre-built systemtap on rawhide or building from
recent source, you should have interactive mode in your systemtap
executable. Feel free to play around with it and let us know what you think.

-- 
David Smith
dsmith@redhat.com
Red Hat
http://www.redhat.com
256.217.0141 (direct)
256.837.0057 (fax)