> cd /root/systemtap

A systemtap script can be as simple as a simgle line. For example,
thge following script places a probepoint on the kernel sys_read() 
function and prints all callers with the function's arguments.

>stap -e 'probe syscall.open {printf("%s: %s\n", execname(), argstr)}'

Most script are a bit longer. (show top.stp)
This script sets a probepoint on all kernel functions beginning with "sys_".
When the probepoint is hit, it increments an entry in the map 
(or associative array) "syscalls" with the key "probefunc()" which returns
the name of the function that was triggered. For example, "sys_read".

There is a timer that is triggered every 5000ms or 5 seconds. That timer
calls the function print_top(). print_top() sorts the syscalls map
and prints the top 20 entries. Then it clears the map.

> ./top.stp

(after stopping "top" go ahead and enter "./sys.stp". It takes a minute
to load this script. Diplay the source in another window and talk 
while it is loading.)

The "top" script looked only at the functions called. If we want more 
detail about the functions, we can use systemtap to examine their local 
arguments and variables. However that would be difficult because each 
system call has different parameters. The Sycall Tapset solves 
this problem. To use it, we set probe points using the syntax "syscall.name"
instead of kernel.function("sys_name"). The Syscall Tapset provides three
defined variables we can use, 
name - the name of the function
argstr - on function entry, a formatted string containing the arguments
retstr - on function exit, the return value and possibly error code

In this example, we filter out programs named "staprun" because this is 
part of the systemtap infrastructure. (It may be filtered out
automatically in the future)

The  next example shows how you can use systemtap to focus on
specific programs or pids. (show prof.stp)

Like the "top" example, this script places probes on all kernel
functions starting with "sys_". Only the probepoint also checks to see
if the tid/pid matches the one returned by "target()" We'll show how 
the target pid is set later.

Unlike the previous examples, this script sets a probe point on all the 
system call returns. When triggered, this probepoint computes the elapsed
time since the function entry. 

To run this script, we must give it a pid to use for the target, or a
program to run, in which case target will be its pid.

>  ./prof.stp -c "top -n5"

--------------------------------

Systemtap can also run in an unsafe mode where you can give
it arbitrary C code to run at probepoints, or modify kernel variables
and structures. This is very dangerous so only experts with root access will
ever be permitted to do this.

(show keyhack.stp)

The next example will modify the local variable "keycode" in the "kdb_keycode"
function in the kernel driver. We indicate it is a local variable by putting
a dollar sign before the name.

./keyhack.stp

(prints error message)

To tell systemtap we really want to run this script, we must use the "-g" flag.

./keyhack.stp -g

(type some keys. "m" should display as "b" in every window) 

This example is not something you would normally want to do. There are 
far better ways to remap a keyboard. What it demonstartes is that Systemtap 
can modify variables in a running kernel.

(show kmalloc.stp)
This next script shows the kind of statistics systemtap can collect.
It collects information about kernel allocations.

> ./kmalloc.stp

Now we can refine this further
(show kmalloc2.stp)

Remember in some previous examples, we used maps or associative arrays. Maps can contain
statistics too.  So we have enhanced the previous script to collect statistics per
program name.  The output might be large so we'll redirect it to a file.

> ./kmalloc2.stp > out

(runs for 10 seconds)

> more out