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