Using SystemTap
short intro, contents of chapter
Using SystemTap
This chapter instructs users how to install SystemTap, and provides an introduction on how to run SystemTap scripts.
Running SystemTap Scripts
- basic commands (e.g. stap), useful options per command (e.g. stap -vv), tool references (man pages, related kernel-doc), references within book (i.e. errors chapter)
- running systemtap scripts
Usage
running SystemTap scripts
running SystemTap scripts
Usage
Usage
stap
stap
Usage
Usage
staprun
staprun
Usage
SystemTap scripts are run through the command stap. stap can run SystemTap scripts from standard input or from file.
SystemTap scripts, how to run
Running stap and staprun requires elevated privileges to the system. However, not all users can be granted root access just to run SystemTap. In some cases, for instance, you may want to allow a non-privileged user to run SystemTap instrumentation on his machine.
To allow ordinary users to run SystemTap without root access, add them to one of these user groups:
stapdev
Usage
stapdev
stapdev
Usage
Members of this group can use stap to run SystemTap scripts, or staprun to run SystemTap instrumentation modules.
Running stap involves compiling SystemTap scripts into kernel modules and
loading them into the kernel. This requires elevated privileges to the system, which are granted
to stapdev members. Unfortunately, such privileges also grant effective root
access to stapdev members. As such, you should only grant
stapdev group membership to users whom you can trust root access.
stapusr
Usage
stapusr
stapusr
Usage
Members of this group can only run staprun to run SystemTap instrumentation modules. In addition, they can only run those modules from /lib/modules/kernel_version/systemtap/. Note that this directory must be owned only by the root user, and must only be writable by the root user.
Below is a list of commonly used stap options:
Usage
options, stap
options, stap
Usage
stap options
-v
Makes the output of the SystemTap session more
verbose. You can repeat this option (for example, stap
-vvv script.stp) to provide more details on the script's execution. This option is particularly useful if you encounter any errors in running the script.
For more information about common SystemTap script errors, refer to .
-o filename
Sends the standard output to file (filename).
-x process ID
Sets the SystemTap handler function target() to the specified process ID. For more information about target(), refer to .
-c command
Sets the SystemTap handler function target() to the specified command. Note that you must use the full path to the specified command; for example, instead of specifying cp, use /bin/cp (as in stap script -c /bin/cp). For more information about target(), refer to .
-e 'script'
Use script
string rather than a file as input for systemtap translator.
You can also instruct stap to run scripts from standard input using the switch -. To illustrate:
Usage
standard input, running scripts from
standard input, running scripts from
Usage
running scripts from standard input
Running Scripts From Standard Input
echo "probe timer.s(1) {exit()}" | stap -
instructs stap to run the script passed by echo to standard input. Any stap options you wish to use should be inserted before the - switch; for instance, to make the example in more verbose, the command would be:
echo "probe timer.s(1) {exit()}" | stap -v -
any other useful options worth noting here for beginners?
For more information about stap, refer to man stap.
To run SystemTap instrumentation (i.e. the kernel module built from SystemTap scripts during a cross-instrumentation), use staprun instead. For more information about staprun and cross-instrumentation, refer to .
Note
The stap options -v and -o also work for staprun. For more information about staprun, refer to man staprun.