Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

Ce contenu n'est pas disponible dans la langue sélectionnée.

Chapter 41. 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 RHEL system.

As an application developer, you can use SystemTap to monitor in fine detail how your application behaves within the RHEL system.

41.1. The purpose of SystemTap
Copier lien

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.

41.2. Installing SystemTap
Copier lien

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: 

    # dnf install systemtap
    Copy to Clipboard Toggle word wrap

  2. Install the required kernel packages:

    1. Using stap-prep: 

      # stap-prep
      Copy to Clipboard Toggle word wrap

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

      # dnf install kernel-debuginfo-$(uname -r) kernel-debuginfo-common-$(uname -m)-$(uname -r) kernel-devel-$(uname -r)
      Copy to Clipboard Toggle word wrap

      $(uname -m) is automatically replaced with the hardware platform of your system and $(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: 

    # stap -v -e 'probe kernel.function("vfs_read") {printf("read performed\n"); exit()}'
    Copy to Clipboard Toggle word wrap

    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.
read performed
Pass 5: run completed in 10usr/40sys/73real ms.
    Copy to Clipboard Toggle word wrap

    where

  • Pass 5: starting run indicates that SystemTap successfully created the instrumentation to probe the kernel and runs the instrumentation.
  • read performed indicates that SystemTap detected the specified event, in this example, a VFS read.
  • Pass 5: run completed in <time> ms indicates that SystemTap executed a valid handler. It displayed text and closed with no errors.

41.3. Privileges to run SystemTap
Copier lien

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.

41.4. Running SystemTap scripts
Copier lien

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 Useful examples of SystemTap scripts or 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
    Copy to Clipboard Toggle word wrap

Procedure

  • Run the SystemTap script:

    • From standard input: 

      # stap -e "probe timer.s(1) {exit()}"
      Copy to Clipboard Toggle word wrap

      This command instructs stap -e to run the script in parenthesis to standard input.

    • From a file: 

      # stap file_name.stp
      Copy to Clipboard Toggle word wrap

41.5. Useful examples of SystemTap scripts
Copier lien

Sample example scripts that are distributed with the installation of SystemTap can be found in the /usr/share/systemtap/examples directory.

You can use the stap command to execute different SystemTap scripts:

Tracing function calls

You can use the para-callgraph.stp SystemTap script to trace function calls and function returns. 

# stap para-callgraph.stp argument1 argument2
Copy to Clipboard Toggle word wrap

The script takes two command-line arguments: The name of the function(s) whose entry/exit you are tracing. An optional trigger function, which enables or disables tracing on a per-thread basis. Tracing in each thread will continue as long as the trigger function has not exited yet.

Monitoring polling applications

You can use the timeout.stp SystemTap script to identify and monitor which applications are polling. Knowing this, you can track unnecessary or excessive polling, which helps you pinpoint areas for improvement in terms of CPU usage and power savings. 

# stap timeout.stp
Copy to Clipboard Toggle word wrap

This script tracks how many times each application uses poll, select, epoll, itimer, futex, nanosleep and Signal system calls over time

Tracking system call volume per process

You can use the syscalls_by_proc.stp SystemTap script to see what processes are performing the highest volume of system calls. It displays the 20 processes performing the most of system calls. 

# stap syscalls_by_proc.stp
Copy to Clipboard Toggle word wrap
Tracing functions called in network socket code

You can use the socket-trace.stp example SystemTap script to trace functions called from the kernel’s net/socket.c file. This helps you identify how each process interacts with the network at the kernel level in fine detail. 

# stap socket-trace.stp
Copy to Clipboard Toggle word wrap
Tracking I/O time for each file read or write

You can use the iotime.stp SystemTap script to monitor the amount of time it takes for each process to read from or write to any file. This helps you to determine what files are slow to load on a system. 

# stap iotime.stp
Copy to Clipboard Toggle word wrap
Track IRQ’s and other processes stealing cycles from a task

You can use the cycle_thief.stp SystemTap script to track the amount of time a task is running and the amount of time it is not running. This helps you to identify which processes are stealing cycles from a task. 

# stap cycle_thief.stp -x pid
Copy to Clipboard Toggle word wrap
Note

You can find more examples and information about SystemTap scripts in the /usr/share/systemtap/examples/index.html file. Open it in a web browser to see a list of all the available scripts and their descriptions.

Retour au début
Red Hat logoGithubredditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance. Découvrez nos récentes mises à jour.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez le Blog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

Theme

© 2025 Red Hat