Chapter 37. Getting started with SystemTap As a system administrator, you can use SystemTap to identify underlying causes of a bug or performance problem on a running Linux system. As an application developer, you can use SystemTap to monitor in fine detail how your application behaves within the Linux system. 37.1. The purpose of SystemTap SystemTap is a tracing and probing tool that you can use to study and monitor the activities of your operating system (particularly, the kernel) in fine detail. SystemTap provides information similar to the output of tools such as netstat , ps , top , and iostat . However, SystemTap provides more filtering and analysis options for collected information. In SystemTap scripts, you specify the information that SystemTap gathers. SystemTap aims to supplement the existing suite of Linux monitoring tools by providing users with the infrastructure to track kernel activity and combining this capability with two attributes: Flexibility the SystemTap framework enables you to develop simple scripts for investigating and monitoring a wide variety of kernel functions, system calls, and other events that occur in kernel space. With this, SystemTap is not so much a tool as it is a system that allows you to develop your own kernel-specific forensic and monitoring tools. Ease-of-Use SystemTap enables you to monitor kernel activity without having to recompile the kernel or reboot the system. 37.2. Installing SystemTap To begin using SystemTap, install the required packages. To use SystemTap on more than one kernel where a system has multiple kernels installed, install the corresponding required kernel packages for each kernel version. Prerequisites You have enabled debug repositories as described in Enabling debug and source repositories . Procedure Install the required SystemTap packages: Install the required kernel packages: Using stap-prep : If stap-prep does not work, install the required kernel packages manually: USD(uname -i) is automatically replaced with the hardware platform of your system and USD(uname -r) is automatically replaced with the version of your running kernel. Verification If the kernel to be probed with SystemTap is currently in use, test if your installation was successful: A successful SystemTap deployment results in an output similar to the following: The last three lines of output (beginning with Pass 5 ) indicate that: 1 SystemTap successfully created the instrumentation to probe the kernel and ran the instrumentation. 2 SystemTap detected the specified event (in this case, A VFS read). 3 SystemTap executed a valid handler (printed text and then closed it with no errors). 37.3. Privileges to run SystemTap Running SystemTap scripts requires elevated system privileges but, in some instances, non-privileged users might need to run SystemTap instrumentation on their machine. To allow users to run SystemTap without root access, add users to both of these user groups: stapdev 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, only grant stapdev group membership to users who can be trusted with root access. stapusr Members of this group can only use staprun to run SystemTap instrumentation modules. In addition, they can only run those modules from the /lib/modules/ kernel_version /systemtap/ directory. This directory must be owned only by the root user, and must only be writable by the root user. 37.4. Running SystemTap scripts You can run SystemTap scripts from standard input or from a file. Sample scripts that are distributed with the installation of SystemTap can be found in the /usr/share/systemtap/examples directory. Prerequisites SystemTap and the associated required kernel packages are installed as described in Installing Systemtap . To run SystemTap scripts as a normal user, add the user to the SystemTap groups: Procedure Run the SystemTap script: From standard input: This command instructs stap to run the script passed by echo to standard input. To add stap options, insert them before the - character. For example, to make the results from this command more verbose, the command is: From a file:

Commands:
yum install systemtap
stap-prep
yum install kernel-debuginfo-USD(uname -r) kernel-debuginfo-common-USD(uname -i)-USD(uname -r) kernel-devel-USD(uname -r)
stap -v -e 'probe kernel.function("vfs_read") {printf("read performed\n"); exit()}'
Pass 1: parsed user script and 45 library script(s) in 340usr/0sys/358real ms. Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 290usr/260sys/568real ms. Pass 3: translated to C into "/tmp/stapiArgLX/stap_e5886fa50499994e6a87aacdc43cd392_399.c" in 490usr/430sys/938real ms. Pass 4: compiled C into "stap_e5886fa50499994e6a87aacdc43cd392_399.ko" in 3310usr/430sys/3714real ms. Pass 5: starting run. 1 read performed 2 Pass 5: run completed in 10usr/40sys/73real ms. 3
usermod --append --groups stapdev,stapusr user-name
echo "probe timer.s(1) {exit()}" | stap -
echo "probe timer.s(1) {exit()}" | stap -v -
stap file_name