2.3. Running SystemTap Scripts
SystemTap scripts are run through the command
stap. stap can run SystemTap scripts from standard input or from file.
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
- Members of this group can use
stapto run SystemTap scripts, orstaprunto run SystemTap instrumentation modules.Runningstapinvolves compiling SystemTap scripts into kernel modules and loading them into the kernel. This requires elevated privileges to the system, which are granted tostapdevmembers. Unfortunately, such privileges also grant effective root access tostapdevmembers. As such, you should only grantstapdevgroup membership to users whom you can trust root access. - stapusr
- Members of this group can only run
staprunto 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:
- -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 Chapter 5, Understanding SystemTap Errors. - -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 abouttarget(), refer to SystemTap Functions. - -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 specifyingcp, use/bin/cp(as instap script -c /bin/cp). For more information abouttarget(), refer to SystemTap Functions. - -e 'script'
- Use
scriptstring 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:
Example 2.1. Running Scripts From Standard Input
echo "probe timer.s(1) {exit()}" | stap -
Example 2.1, “Running Scripts From Standard Input” 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 Example 2.1, “Running Scripts From Standard Input” more verbose, the command would be:
echo "probe timer.s(1) {exit()}" | stap -v -
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 Section 2.2, “Generating Instrumentation for Other Computers”.
Note
The
stap options -v and -o also work for staprun. For more information about staprun, refer to man staprun.
