SystemTap Tapset Reference Manual 2008-2025 Red Hat, Inc. and others SystemTap Hackers This documentation is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. For more details see the file COPYING in the source distribution of Linux. Introduction SystemTap provides free software (GPL) infrastructure to simplify the gathering of information about the running Linux system. This assists diagnosis of a performance or functional problem. SystemTap eliminates the need for the developer to go through the tedious and disruptive instrument, recompile, install, and reboot sequence that may be otherwise required to collect data. SystemTap provides a simple command line interface and scripting language for writing instrumentation for a live running kernel. The instrumentation makes extensive use of the probe points and functions provided in the tapset library. This document describes the various probe points and functions.
Tapset Name Format In this guide, tapset definitions appear in the following format: name:return (parameters) definition The return field specifies what data type the tapset extracts and returns from the kernel during a probe (and thus, returns). Tapsets use 2 data types for return: long (tapset extracts and returns an integer) and string (tapset extracts and returns a string). In some cases, tapsets do not have a return value. This simply means that the tapset does not extract anything from the kernel. This is common among asynchronous events such as timers, exit functions, and print functions.
Context Functions The context functions provide additional information about where an event occurred. These functions can provide information such as a backtrace to where the event occurred and the current register values for the processor. !Itapset/context.stp !Itapset/linux/context.stp !Itapset/linux/context-envvar.stp !Itapset/linux/context-symbols.stp !Itapset/linux/ucontext.stp !Itapset/linux/ucontext-symbols.stp !Itapset/linux/context-unwind.stp !Itapset/linux/context-caller.stp !Itapset/linux/ucontext-unwind.stp !Itapset/linux/task.stp !Itapset/linux/task_ancestry.stp !Itapset/pn.stp !Itapset/linux/pstrace.stp !Itapset/registers.stp Timestamp Functions Each timestamp function returns a value to indicate when a function is executed. These returned values can then be used to indicate when an event occurred, provide an ordering for events, or compute the amount of time elapsed between two time stamps. !Itapset/linux/timestamp.stp !Itapset/linux/timestamp_gtod.stp !Itapset/linux/timestamp_monotonic.stp !Itapset/stopwatch.stp Time utility functions Utility functions to turn seconds since the epoch (as returned by the timestamp function gettimeofday_s()) into a human readable date/time strings. !Itapset/linux/ctime.stp !Itapset/linux/tzinfo.stp !Itapset/tzinfo.stp Shell command functions Utility functions to enqueue shell commands. !Itapset/system.stp Memory Tapset This family of probe points is used to probe memory-related events or query the memory usage of the current process. It contains the following probe points: !Itapset/linux/memory.stp !Itapset/linux/proc_mem.stp Task Time Tapset This tapset defines utility functions to query time related properties of the current tasks, translate those in miliseconds and human readable strings. !Itapset/linux/task_time.stp Scheduler Tapset This family of probe points is used to probe the task scheduler activities. It contains the following probe points: !Itapset/linux/scheduler.stp IO Scheduler and block IO Tapset This family of probe points is used to probe block IO layer and IO scheduler activities. It contains the following probe points: !Itapset/linux/ioscheduler.stp !Itapset/linux/ioblock.stp SCSI Tapset This family of probe points is used to probe SCSI activities. It contains the following probe points: !Itapset/linux/scsi.stp TTY Tapset This family of probe points is used to probe TTY (Teletype) activities. It contains the following probe points: !Itapset/linux/tty.stp Interrupt Request (IRQ) Tapset This family of probe points is used to probe interrupt request (IRQ) activities. It contains the following probe points: !Itapset/linux/irq.stp Networking Tapset This family of probe points is used to probe the activities of the network device and protocol layers. !Itapset/linux/networking.stp !Itapset/linux/tcp.stp !Itapset/linux/udp.stp !Itapset/linux/ip.stp !Itapset/linux/inet.stp !Itapset/linux/rpc.stp !Itapset/linux/netfilter.stp Socket Tapset This family of probe points is used to probe socket activities. It contains the following probe points: !Itapset/linux/socket.stp !Itapset/linux/inet_sock.stp SNMP Information Tapset This family of probe points is used to probe socket activities to provide SNMP type information. It contains the following functions and probe points: !Itapset/linux/ipmib.stp !Itapset/linux/ipmib-filter-default.stp !Itapset/linux/tcpmib.stp !Itapset/linux/tcpmib-filter-default.stp !Itapset/linux/linuxmib.stp !Itapset/linux/linuxmib-filter-default.stp Kernel Process Tapset This family of probe points is used to probe process-related activities. It contains the following probe points: !Itapset/linux/kprocess.stp !Itapset/linux/target_set.stp !Itapset/linux/loadavg.stp Signal Tapset This family of probe points is used to probe signal activities. It contains the following probe points: !Itapset/linux/signal.stp Errno Tapset This set of functions is used to handle errno number values. It contains the following functions: !Itapset/errno.stp RLIMIT Tapset This set of functions is used to handle string which defines resource limits (RLIMIT_*) and returns corresponding number of resource limit. It contains the following functions: !Itapset/linux/rlimit.stp Device Tapset This set of functions is used to handle kernel and userspace device numbers. It contains the following functions: !Itapset/linux/dev.stp Directory-entry (dentry) Tapset This family of functions is used to map kernel VFS directory entry pointers to file or full path names. !Itapset/linux/dentry.stp Logging Tapset This family of functions is used to send simple message strings to various destinations. !Itapset/logging.stp !Itapset/linux/logging.stp Queue Statistics Tapset This family of functions is used to track performance of queuing systems. !Itapset/queue_stats.stp Random functions Tapset These functions deal with random number generation. !Itapset/random.stp String and data retrieving functions Tapset Functions to retrieve strings and other primitive types from the kernel or a user space programs based on addresses. All strings are of a maximum length given by MAXSTRINGLEN. !Itapset/linux/conversions.stp !Itapset/linux/atomic.stp !Itapset/uconversions.stp String and data writing functions Tapset The SystemTap guru mode can be used to test error handling in kernel code by simulating faults. The functions in the this tapset provide standard methods of writing to primitive types in the kernel's memory. All the functions in this tapset require the use of guru mode (-g). !Itapset/linux/conversions-guru.stp !Itapset/uconversions-guru.stp Guru tapsets Functions to deliberately interfere with the system's behavior, in order to inject faults or improve observability. All the functions in this tapset require the use of guru mode (-g). !Itapset/linux/guru-delay.stp !Itapset/linux/panic.stp !Itapset/linux/guru-signal.stp A collection of standard string functions Functions to get the length, a substring, getting at individual characters, string seaching, escaping, tokenizing, and converting strings to longs. !Itapset/string.stp !Itapset/tokenize.stp !Itapset/regex.stp Utility functions for using ansi control chars in logs Utility functions for logging using ansi control characters. This lets you manipulate the cursor position and character color output and attributes of log messages. !Itapset/ansi.stp !Itapset/indent.stp SystemTap Translator Tapset This family of user-space probe points is used to probe the operation of the SystemTap translator (stap) and run command (staprun). The tapset includes probes to watch the various phases of SystemTap and SystemTap's management of instrumentation cache. It contains the following probe points: !Itapset/stap_staticmarkers.stp Network File Storage Tapsets This family of probe points is used to probe network file storage functions and operations. !Itapset/linux/nfs_proc.stp !Itapset/linux/nfs.stp !Itapset/linux/nfsd.stp !Itapset/linux/nfsderrno.stp Speculation This family of functions provides the ability to speculative record information and then at a later point in the SystemTap script either commit the information or discard it. !Itapset/speculative.stp JSON Tapset This family of probe points, functions, and macros is used to output data in JSON format. It contains the following probe points, functions, and macros: !Itapset/linux/json.stp !Itapset/linux/json.stpm Output file switching Tapset Utility function to allow switching of output files. !Itapset/switchfile.stp Floating point processing Tapset Utility functions to extract, convert, and perform arithmetic on IEEE-754 doubles. !Itapset/floatingpoint.stp Syscall Any Tapset This family of probe points is designed to provide low cost instrumentation for cases where only the syscall name (or number) and return value are required and there is no need for the detailed syscall argument values. They are restricted versions of syscall.* and syscall.*.return. !Itapset/linux/syscall_any.stp CVE Livepatching Tapset Utility functions and control variables which can be used to create standardized CVE patches. The globals are cve_notify_p (non-zero if the patch should be verbose), cve_fix_p (non-zero if the fix should be applied), cve_trace_p (non-zero if only a trace should be run), cve_enabled_p (non-zero if the patch should be enabled). The controls can be changed in /proc/systemtap/MODULE_NAME/* and the recorded prometheus metrics can be viewed in the same directory. !Itapset/livepatch.stp !Syscalls