Chapter 25. 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.

25.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.

25.2. Deploying SystemTap

To use SystemTap, you must install the associated SystemTap and kernel packages.

25.2.1. Enabling debug and source repositories

A standard installation of Red Hat Enterprise Linux does not enable the debug and source repositories. These repositories contain information needed to debug the system components and measure their performance.

Procedure

  • Enable the source and debug information package channels:

    # subscription-manager repos --enable rhel-8-for-$(uname -i)-baseos-debug-rpms
    # subscription-manager repos --enable rhel-8-for-$(uname -i)-baseos-source-rpms
    # subscription-manager repos --enable rhel-8-for-$(uname -i)-appstream-debug-rpms
    # subscription-manager repos --enable rhel-8-for-$(uname -i)-appstream-source-rpms

    The $(uname -i) part is automatically replaced with a matching value for architecture of your system:

    Architecture nameValue

    64-bit Intel and AMD

    x86_64

    64-bit ARM

    aarch64

    IBM POWER

    ppc64le

    IBM Z

    s390x

25.2.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

Procedure

  1. Install the required SystemTap packages:

    # yum install systemtap
  2. Install the required kernel packages:

    1. Using stap-prep:

      # stap-prep
    2. If stap-prep does not work, install the required kernel packages manually:

      # yum install kernel-debuginfo-$(uname -r) kernel-debuginfo-common-$(uname -i)-$(uname -r) kernel-devel-$(uname -r)

      $(uname -i) is automatically replaced with the hardware platform of your system and $(uname -r) is automatically replaced with the version of your running kernel.

Verification steps

  • If the kernel to be probed with SystemTap is currently in use, test if your installation was successful:

    # stap -v -e 'probe kernel.function("vfs_read") {printf("read performed\n"); exit()}'

    A successful SystemTap deployment results in an 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. 1
    read performed 2
    Pass 5: run completed in 10usr/40sys/73real ms. 3

    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).

25.3. Cross-instrumentation of SystemTap

25.3.1. SystemTap cross-instrumentation

When you run a SystemTap script, a kernel module is built out of that script. SystemTap then loads the module into the kernel.

Normally, SystemTap scripts can run only on systems where SystemTap is deployed. To run SystemTap on ten systems, SystemTap needs to be deployed on all those systems. In some cases, this might be neither feasible nor desired. For example, corporate policy might prohibit you from installing packages that provide compilers or debug information on specific machines, which will prevent the deployment of SystemTap.

To work around this, use cross-instrumentation. Cross-instrumentation is the process of generating SystemTap instrumentation modules from a SystemTap script on one system to be used on another system. This process offers the following benefits:

  • The kernel information packages for various machines can be installed on a single host machine.
Caution

Kernel packaging bugs may prevent this. In such cases, the kernel-debuginfo and kernel-devel packages for the host system and target system must match. If this occurs, report the bug at https://bugzilla.redhat.com/.

  • Each target machine needs only one package to be installed to use the generated SystemTap instrumentation module: systemtap-runtime.
Important

The host system must be the same architecture and running the same distribution of Linux as the target system in order for the built instrumentation module to work.

Terminology
instrumentation module
The kernel module built from a SystemTap script; the SystemTap module is built on the host system, and will be loaded on the target kernel of the target system.
host system
The system on which the instrumentation modules (from SystemTap scripts) are compiled, to be loaded on target systems.
target system
The system in which the instrumentation module is being built (from SystemTap scripts).
target kernel
The kernel of the target system. This is the kernel that loads and runs the instrumentation module.

25.3.2. Initializing cross-instrumentation of SystemTap

Initialize cross-instrumentation of SystemTap to build SystemTap instrumentation modules from a SystemTap script on one system and use them on another system that does not have SystemTap fully deployed.

Prerequisites

  • SystemTap is installed on the host system as described in Installing SystemTap.
  • Both the host system and target system are the same architecture.
  • Both the host system and target system are running the same major version of Red Hat Enterprise Linux (such as Red Hat Enterprise Linux 8), they can be running different minor versions (such as 8.1 and 8.2).
Caution

Kernel packaging bugs may prevent multiple kernel-debuginfo and kernel-devel packages from being installed on one system. In such cases, the minor version for the host system and target system must match. If this occurs, report the bug at https://bugzilla.redhat.com/.

Procedure

  1. Determine the kernel running on each target system:

    $ uname -r

    Repeat this step for each target system.

  2. Install the package required to run pre-compiled modules on each target system:

    # yum install systemtap-runtime
  3. On the host system, install the target kernel and related packages for each target system by the method described in installing SystemTap.
  4. Build an instrumentation module on the host system, copy to and run on the target system either:

    1. Using remote implementation:

      # stap --remote target_system script

      This command remotely implements the specified script on the target system. You must ensure an SSH connection can be made to the target system from the host system for this to be successful.

    2. Manually:

      1. Build the instrumentation module on the host system:

        # stap -r kernel_version script -m module_name -p 4

        Here, kernel_version refers to the version of the target kernel determined in step 1, script refers to the script to be converted into an instrumentation module, and module_name is the desired name of the instrumentation module. The -p4 option tells SystemTap to not load and run the compiled module.

      2. Once the instrumentation module is compiled, copy it to the target system and load it using the following command:

        # staprun module_name.ko
        Note

        Running a pre-compiled module only requires the systemtap-runtime package.

25.4. Running SystemTap scripts

25.4.1. 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.

25.4.2. 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

  1. SystemTap and the associated required kernel packages are installed as described in installing SystemTap.
  2. To run SystemTap scripts as a normal user, add the user to the SystemTap groups:

    # usermod --append --groups
    stapdev,stapusr user-name

Procedure

  • Run the SystemTap script:

    • From standard input:

      # echo "probe timer.s(1) {exit()}" | stap -

      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:

      # echo "probe timer.s(1) {exit()}" | stap -v -
    • From a file:

      # stap file_name