Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

Chapter 2. Using SystemTap

This chapter instructs users how to install SystemTap, and provides an introduction on how to run SystemTap scripts.

2.1. Installation and Setup

To deploy SystemTap, SystemTap packages along with the corresponding set of -devel, -debuginfo and -debuginfo-common-arch packages for the kernel need to be installed. To use SystemTap on more than one kernel where a system has multiple kernels installed, install the -devel and -debuginfo packages for each of those kernel versions.
These procedures will be discussed in detail in the following sections.

Important

Many users confuse -debuginfo with -debug. Remember that the deployment of SystemTap requires the installation of the -debuginfo package of the kernel, not the -debug version of the kernel.

2.1.1. Installing SystemTap

To deploy SystemTap, install the following RPM packages:
  • systemtap
  • systemtap-runtime
Assuming that yum is installed in the system, these two RPM packages can be installed with yum install systemtap systemtap-runtime. Install the required kernel information packages before using SystemTap.

2.1.2. Installing Required Kernel Information RPM packages

SystemTap needs information about the kernel in order to place instrumentation in it (that is probe it). This information, which allows SystemTap to generate the code for the instrumentation, is contained in the matching -devel, -debuginfo, and -debuginfo-common-arch packages for the kernel. The necessary -devel and -debuginfo packages for the ordinary "vanilla" kernel are as follows:
  • kernel-debuginfo
  • kernel-debuginfo-common-arch
  • kernel-devel
Likewise, the necessary packages for the PAE kernel would be kernel-PAE-debuginfo, kernel-PAE-debuginfo-common-arch ,and kernel-PAE-devel.
To determine what kernel your system is currently using, use: 
uname -r
For example, if you wish to use SystemTap on kernel version 2.6.32-53.el6 on an machine with the 32-bit AMD and Intel architecture, then you would need to download and install the following RPM packages:
  • kernel-debuginfo-2.6.32-53.el6.i686.rpm
  • kernel-debuginfo-common-i686-2.6.32-53.el6.i686.rpm
  • kernel-devel-2.6.32-53.el6.i686.rpm

Important

The version, variant, and architecture of the -devel, -debuginfo and -debuginfo-common-arch packages must match the kernel to be probed with SystemTap exactly.
To obtain a list of the channels SystemTap needs on the system, use the following script: 
#! /bin/bash
pkg=`rpm -q --whatprovides "redhat-release"`
releasever=`rpm -q --qf "%{version}" $pkg`
variant=`echo $releasever | tr -d "[:digit:]" | tr "[:upper:]" "[:lower:]" `
if test -z "$variant"; then
  echo "No Red Hat Enterprise Linux variant (workstation/client/server) found."
  exit 1
fi
version=`echo $releasever | tr -cd "[:digit:]"`
base=`uname -i`
echo "rhel-$base-$variant-$version"
echo "rhel-$base-$variant-$version-debuginfo"
echo "rhel-$base-$variant-optional-$version-debuginfo"
echo "rhel-$base-$variant-optional-$version"
After the channels have been added, install the required -devel, debuginfo, and debuginfo-install arch packages for the kernel using the command debuginfo-install kernelname-version. Replace kernelname with the appropriate kernel variant name (for example, kernel-PAE), and version with the target kernel's version. For example, to install the required kernel information packages for the kernel-PAE-2.6.32-53.el6 kernel, run: debuginfo-install kernel-PAE-2.6.32-53.el6

2.1.3. Initial Testing

If the kernel to be probed with SystemTap is currently being used, it is possible to immediately test whether the deployment was successful. If a different kernel is to be probed, reboot and load the appropriate kernel.
To start the test, run the command stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'. This command simply instructs SystemTap to print read performed then exit properly once a virtual file system read is detected. If the SystemTap deployment was successful, you should get output similar to the following: 
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.
read performed
Pass 5: run completed in 10usr/40sys/73real ms.
The last three lines of the output (that is beginning with Pass 5) indicate that SystemTap was able to successfully create the instrumentation to probe the kernel, run the instrumentation, detect the event being probed (in this case, a virtual file system read), and execute a valid handler (print text then close it with no errors).