The systemtap translator supports the following options. Any
other option prints a list of supported options. Options may be
given on the command line, as usual. If the file
$SYSTEMTAP_DIR/rc exist, options are also loaded from there and
interpreted first. ($SYSTEMTAP_DIR defaults to $HOME/.systemtap
if unset.)
In some cases, the default value of an option depends on
particular system configuration and thus can't be mentioned here
directly. In some of those cases running "stap --help" might
display the default.
- Use standard input instead of a given FILENAME as probe
language input, unless -e SCRIPT is given.
-h --help
Show help message.
-V --version
Show version message.
-p NUM Stop after pass NUM. The passes are numbered 1-5: parse,
elaborate, translate, compile, run. See the PROCESSING
section for details.
-v Increase verbosity for all passes. Produce a larger
volume of informative (?) output each time option
repeated.
--vp ABCDE
Increase verbosity on a per-pass basis. For example,
"--vp 002" adds 2 units of verbosity to pass 3 only. The
combination "-v --vp 00004" adds 1 unit of verbosity for
all passes, and 4 more for pass 5.
-k Keep the temporary directory after all processing. This
may be useful in order to examine the generated C code, or
to reuse the compiled kernel object.
-g Guru mode. Enable parsing of unsafe expert-level
constructs like embedded C.
-P Prologue-searching mode. This is equivalent to
--prologue-searching=always. Activate heuristics to work
around incorrect debugging information for function
parameter $context variables.
-u Unoptimized mode. Disable unused code elision and many
other optimizations during elaboration / translation.
-w Suppressed warnings mode. Disables all warning messages.
-W Treat all warnings as errors.
-b Use bulk mode (percpu files) for kernel-to-user data
transfer. Use the stap-merge program to multiplex them
back together later.
-i --interactive
Interactive mode. Enable an interface to build the
systemtap script incrementally and interactively.
-t Collect timing information on the number of times probe
executes and average amount of time spent in each probe-
point. Also shows the derivation for each probe-point.
-s NUM Use NUM megabyte buffers for kernel-to-user data transfer.
On a multiprocessor in bulk mode, this is a per-processor
amount.
-I DIR Add the given directory to the tapset search directory.
See the description of pass 2 for details.
-D NAME=VALUE
Add the given C preprocessor directive to the module
Makefile. These can be used to override limit parameters
described below.
-B NAME=VALUE
In kernel-runtime mode, add the given make directive to
the kernel module build's make invocation. These can be
used to add or override kconfig options. For example, use
-B CONFIG_DEBUG_INFO=y
to add debugging information.
-B FLAG
In dyninst-runtime mode, add the given parameter to the
compiler CFLAGS used for building the dyninst shared
library. For example, use
-B -g
to add debugging information.
-a ARCH
Use a cross-compilation mode for the given target
architecture. This requires access to the cross-compiler
and the kernel build tree, and goes along with the
-B CROSS_COMPILE=arch-tool-prefix-
and
-r /build/tree
options.
--modinfo NAME=VALUE
Add the name/value pair as a MODULE_INFO macro call to the
generated module. This may be useful to inform or
override various module-related checks in the kernel.
-G NAME=VALUE
Sets the value of global variable NAME to VALUE when
staprun is invoked. This applies to scalar variables
declared global in the script/tapset.
-R DIR Look for the systemtap runtime sources in the given
directory. Your DIR default can be seen using "stap
--help".
-r /DIR
Build for kernel in given build tree. Can also be set with
the SYSTEMTAP_RELEASE environment variable.
-r RELEASE
Build for kernel in build tree /lib/modules/RELEASE/build.
Can also be set with the SYSTEMTAP_RELEASE environment
variable.
-m MODULE
Use the given name for the generated kernel object module,
instead of a unique randomized name. The generated kernel
object module is copied to the current directory.
-d MODULE
Add symbol/unwind information for the given module into
the kernel object module. This may enable symbolic
tracebacks from those modules/programs, even if they do
not have an explicit probe placed into them.
--ldd Add symbol/unwind information for all user-space shared
libraries suspected by ldd to be necessary for user-space
binaries being probed or listed with the -d option.
Caution: this can make the probe modules considerably
larger. Note that this option does not deal with kernel-
space modules: see instead --all-modules below.
--all-modules
Equivalent to specifying "-dkernel" and a "-d" for each
kernel module that is currently loaded. Caution: this can
make the probe modules considerably larger.
-o FILE
Send standard output to named file. In bulk mode, percpu
files will start with FILE_ (FILE_cpu with -F) followed by
the cpu number. This supports strftime(3) formats for
FILE.
-c CMD Start the probes, run CMD, and exit when CMD finishes.
This also has the effect of setting target() to the pid of
the command ran.
-x PID Sets target() to PID. This allows scripts to be written
that filter on a specific process. Scripts run independent
of the PID's lifespan.
-e SCRIPT
Run the given SCRIPT specified on the command line.
-E SCRIPT
Run the given SCRIPT specified. This SCRIPT is run in
addition to the main script specified, through -e, or as a
script file. This option can be repeated to run multiple
scripts, and can be used in listing mode (-l/-L).
-l PROBE
Instead of running a probe script, just list all available
probe points matching the given single probe point. The
pattern may include wildcards and aliases, but not comma-
separated multiple probe points. The process result code
will indicate failure if there are no matches.
% stap -e 'probe syscall.* { }'
[...]
% stap -l 'syscall.*'
syscall.accept
[...]
syscall.writev
-L PROBE
Similar to "-l", but list matching probe points plus their
available context variables. When -v is set with -L, the
output includes duplicate probe points which are
distinguished by their PC address.
% stap -L 'process("/lib64/libpython*.so.*").mark("*")'
process("/usr/lib64/libpython2.7.so.1.0").mark("function__entry") $arg1:long $arg2:long $arg3:long
process("/usr/lib64/libpython2.7.so.1.0").mark("function__return") $arg1:long $arg2:long $arg3:long
process("/usr/lib64/libpython3.6m.so.1.0").mark("function__entry") $arg1:long $arg2:long $arg3:long
process("/usr/lib64/libpython3.6m.so.1.0").mark("function__return") $arg1:long $arg2:long $arg3:long
process("/usr/lib64/libpython3.6m.so.1.0").mark("gc__done") $arg1:long
process("/usr/lib64/libpython3.6m.so.1.0").mark("gc__start") $arg1:long
process("/usr/lib64/libpython3.6m.so.1.0").mark("line") $arg1:long $arg2:long $arg3:long
-F Without -o option, load module and start probes, then
detach from the module leaving the probes running. With
-o option, run staprun in background as a daemon and show
its pid.
-S size[,N]
Sets the maximum size of output file and the maximum
number of output files. If the size of output file will
exceed size , systemtap switches output file to the next
file. And if the number of output files exceed N ,
systemtap removes the oldest output file. You can omit the
second argument.
-T TIMEOUT
Exit the script after TIMEOUT seconds.
--skip-badvars
Ignore unresolvable or run-time-inaccessible context
variables and substitute with 0, without errors.
--prologue-searching[=WHEN]
Prologue-searching mode. Activate heuristics to work
around incorrect debugging information for function
parameter $context variables. WHEN can be either "never",
"always", or "auto" (i.e. enabled by heuristic). If WHEN
is missing, then "always" is assumed. If the option is
missing, then "auto" is assumed.
--suppress-handler-errors
Wrap all probe handlers into something like this
try { ... } catch { next }
block, which causes any runtime errors to be quietly
suppressed. Suppressed errors do not count against
MAXERRORS limits. In this mode, the MAXSKIPPED limits are
also suppressed, so that many errors and skipped probes
may be accumulated during a script's runtime. Any overall
counts will still be reported at shutdown.
--compatible VERSION
Suppress recent script language or tapset changes which
are incompatible with given older version of systemtap.
This may be useful if a much older systemtap script fails
to run. See the DEPRECATION section for more details.
--check-version
This option is used to check if the active script has any
constructs that may be systemtap version specific. See
the DEPRECATION section for more details.
--clean-cache
This option prunes stale entries from the cache directory.
This is normally done automatically after successful runs,
but this option will trigger the cleanup manually and then
exit. See the CACHING section for more details about
cache limits.
--color[=WHEN], --colour[=WHEN]
This option controls coloring of error messages. WHEN can
be either "never", "always", or "auto" (i.e. enable only
if at a terminal). If WHEN is missing, then "always" is
assumed. If the option is missing, then "auto" is assumed.
Colors can be modified using the SYSTEMTAP_COLORS
environment variable. The format must be of the form
key1=val1:key2=val2:key3=val3 ...etc. Valid keys are
"error", "warning", "source", "caret", and "token".
Values constitute Select Graphic Rendition (SGR)
parameter(s). Consult the documentation of your terminal
for the SGRs it supports. As an example, the default
colors would be expressed as
error=01;31:warning=00;33:source=00;34:caret=01:token=01.
If SYSTEMTAP_COLORS is absent, the default colors will be
used. If it is empty or invalid, coloring is turned off.
--disable-cache
This option disables all use of the cache directory. No
files will be either read from or written to the cache.
--poison-cache
This option treats files in the cache directory as
invalid. No files will be read from the cache, but
resulting files from this run will still be written to the
cache. This is meant as a troubleshooting aid when stap's
cached behavior seems to be misbehaving. If it helped,
there is a probably a bug in systemtap that the developers
would like you to report.
--privilege[=stapusr | =stapsys | =stapdev]
This option instructs stap to examine the script looking
for constructs which are not allowed for the specified
privilege level (see UNPRIVILEGED USERS). Compilation
fails if any such constructs are used. If stapusr or
stapsys are specified when using a compile server (see
--use-server), the server will examine the script and, if
compilation succeeds, the server will cryptographically
sign the resulting kernel module, certifying that is it
safe for use by users at the specified privilege level.
If --privilege has not been specified, -pN has not been
specified with N < 5, and the invoking user is not root,
and is not a member of the group stapdev, then stap will
automatically add the appropriate --privilege option to
the options already specified.
--unprivileged
This option is equivalent to --privilege=stapusr.
--use-server[=HOSTNAME[:PORT] | =IP_ADDRESS[:PORT] |
=CERT_SERIAL]
Specify compile-server(s) to be used for compilation
and/or in conjunction with --list-servers and
--trust-servers (see below) for listing. If no argument is
supplied, then the default in unprivileged mode (see
--privilege) is to select compatible servers which are
trusted as SSL peers and as module signers and currently
online. Otherwise the default is to select compatible
servers which are trusted as SSL peers and currently
online. --use-server may be specified more than once, in
which case a list of servers is accumulated in the order
specified. Servers may be specified by host name, ip
address, or by certificate serial number (obtained using
--list-servers). The latter is most commonly used when
adding or revoking trust in a server (see --trust-servers
below). If a server is specified by host name or ip
address, then an optional port number may be specified.
This is useful for accessing servers which are not on the
local network or to specify a particular server.
IP addresses may be IPv4 or IPv6 addresses.
If a particular IPv6 address is link local and exists on
more than one interface, the intended interface may be
specified by appending the address with a percent sign (%)
followed by the intended interface name. For example,
"fe80::5eff:35ff:fe07:55ca%eth0".
In order to specify a port number with an IPv6 address, it
is necessary to enclose the IPv6 address in square
brackets ([]) in order to separate the port number from
the rest of the address. For example,
"[fe80::5eff:35ff:fe07:55ca]:5000" or
"[fe80::5eff:35ff:fe07:55ca%eth0]:5000".
If --use-server has not been specified, -pN has not been
specified with N < 5, and the invoking user not root, is
not a member of the group stapdev, but is a member of the
group stapusr, then stap will automatically add
--use-server to the options already specified.
--use-server-on-error[=yes|=no]
Instructs stap to retry compilation of a script using a
compile server if compilation on the local host fails in a
manner which suggests that it might succeed using a
server. If this option is not specified, the default is
no. If no argument is provided, then the default is yes.
Compilation will be retried for certain types of errors
(e.g. insufficient data or resources) which may not occur
during re-compilation by a compile server. Compile servers
will be selected automatically for the re-compilation
attempt as if --use-server was specified with no
arguments.
--list-servers[=SERVERS]
Display the status of the requested SERVERS, where SERVERS
is a comma-separated list of server attributes. The list
of attributes is combined to filter the list of servers
displayed. Supported attributes are:
all specifies all known servers (trusted SSL peers,
trusted module signers, online servers).
specified
specifies servers specified using --use-server.
online filters the output by retaining information about
servers which are currently online.
trusted
filters the output by retaining information about
servers which are trusted as SSL peers.
signer filters the output by retaining information about
servers which are trusted as module signers (see
--privilege).
compatible
filters the output by retaining information about
servers which are compatible with the current
kernel release and architecture.
If no argument is provided, then the default is specified.
If no servers were specified using --use-server, then the
default servers for --use-server are listed.
Note that --list-servers uses the avahi-daemon service to
detect online servers. If this service is not available,
then --list-servers will fail to detect any online
servers. In order for --list-servers to detect servers
listening on IPv6 addresses, the avahi-daemon
configuration file /etc/avahi/avahi-daemon.conf must
contain an active "use-ipv6=yes" line. The service must be
restarted after adding this line in order for IPv6 to be
enabled.
--trust-servers[=TRUST_SPEC]
Grant or revoke trust in compile-servers, specified using
--use-server as specified by TRUST_SPEC, where TRUST_SPEC
is a comma-separated list specifying the trust which is to
be granted or revoked. Supported elements are:
ssl trust the specified servers as SSL peers.
signer trust the specified servers as module signers (see
--privilege). Only root can specify signer.
all-users
grant trust as an ssl peer for all users on the
local host. The default is to grant trust as an ssl
peer for the current user only. Trust as a module
signer is always granted for all users. Only root
can specify all-users.
revoke revoke the specified trust. The default is to grant
it.
no-prompt
do not prompt the user for confirmation before
carrying out the requested action. The default is
to prompt the user for confirmation.
If no argument is provided, then the default is ssl. If
no servers were specified using --use-server, then no
trust will be granted or revoked.
Unless no-prompt has been specified, the user will be
prompted to confirm the trust to be granted or revoked
before the operation is performed.
--dump-probe-types
Dumps a list of supported probe types and exits. If
--privilege=stapusr is also specified, the list will be
limited to probe types available to unprivileged users.
--dump-probe-aliases
Dumps a list of all probe aliases found in library files
and exits.
--dump-functions
Dumps a list of all the public functions found in library
files and exits. Also includes their parameters and types.
A function of type 'unknown' indicates a function that
does not return a value. Note that not all
function/parameter types may be resolved (these are also
shown by 'unknown'). This features is very memory-
intensive and thus may not work properly with --use-server
if the target server imposes an rlimit on process memory
(i.e. through the ~stap-server/.systemtap/rc configuration
file, see stap-server(8)).
--remote URL
Set the execution target to the given host. This option
may be repeated to target multiple execution targets.
Passes 1-4 are completed locally as normal to build the
script, and then pass 5 will copy the module to the target
and run it. Acceptable URL forms include:
[USER@]HOSTNAME, ssh://[USER@]HOSTNAME
This mode uses ssh, optionally using a username not
matching your own. If a custom ssh_config file is
in use, add SendEnv LANG to retain
internationalization functionality.
libvirt://DOMAIN, libvirt://DOMAIN/LIBVIRT_URI
This mode uses stapvirt to execute the script on a
domain managed by libvirt. Optionally, LIBVIRT_URI
may be specified to connect to a specific driver
and/or a remote host. For example, to connect to
the local privileged QEMU driver, use:
--remote libvirt://MyDomain/qemu:///system
See the page at <http://libvirt.org/uri.html> for
supported URIs. Also see stapvirt(1) for more
information on how to prepare the domain for stap
probing.
unix:PATH
This mode connects to a UNIX socket. This can be
used with a QEMU virtio-serial port for executing
scripts inside a running virtual machine.
direct://
Special loopback mode to run on the local host.
--remote-prefix
Prefix each line of remote output with "N: ", where N is
the index of the remote execution target from which the
given line originated.
--download-debuginfo[=OPTION]
Enable, disable or set a timeout for the automatic
debuginfo downloading feature offered by abrt as specified
by OPTION, where OPTION is one of the following:
yes enable automatic downloading of debuginfo with no
timeout. This is the same as not providing an
OPTION value to --download-debuginfo
no explicitly disable automatic downloading of
debuginfo. This is the same as not using the option
at all.
ask show abrt output, and ask before continuing
download. No timeout will be set.
<timeout>
specify a timeout as a positive number to stop the
download if it is taking longer than <timeout>
seconds.
--rlimit-as=NUM
Specify the maximum size of the process's virtual memory
(address space), in bytes.
--rlimit-cpu=NUM
Specify the CPU time limit, in seconds.
--rlimit-nproc=NUM
Specify the maximum number of processes that can be
created.
--rlimit-stack=NUM
Specify the maximum size of the process stack, in bytes.
--rlimit-fsize=NUM
Specify the maximum size of files that the process may
create, in bytes.
--sysroot=DIR
Specify sysroot directory where target files (executables,
libraries, etc.) are located. With -r RELEASE, the
sysroot will be searched for the appropriate kernel build
directory. With -r /DIR, however, the sysroot will not be
used to find the kernel build.
--sysenv=VAR=VALUE
Provide an alternate value for an environment variable
where the value on a remote system differs. Path
variables (e.g. PATH, LD_LIBRARY_PATH) are assumed to be
relative to the directory provided by --sysroot, if
provided.
--suppress-time-limits
Disable -DSTP_OVERLOAD related options as well as
-DMAXACTION and -DMAXTRYLOCK. This option requires guru
mode.
--runtime=MODE
Set the pass-5 runtime mode. Valid options are kernel
(default), dyninst and bpf. See ALTERNATE RUNTIMES below
for more information.
--dyninst
Shorthand for --runtime=dyninst.
--bpf Shorthand for --runtime=bpf.
--save-uprobes
On machines that require SystemTap to build its own
uprobes module (kernels prior to version 3.5), this option
instructs SystemTap to also save a copy of the module in
the current directory (creating a new "uprobes" directory
first).
--target-namespaces=PID
Allow for a set of target namespaces to be set based on
the namespaces the given PID is in. This is for
namespace-aware tapset functions. If the target namespaces
was not set, the target defaults to the stap process'
namespaces.
--monitor=INTERVAL
Enables an interface to display status information about
the module(uptime, module name, invoker uid, memory sizes,
global variables, list of probes with their statistics).
An optional argument INTERVAL can be supplied to set the
refresh rate in seconds of the status window. The module
can also be controlled by a list of commands using the
following keys:
c Resets all global variables to their initial values
or zeroes them if they did not have an initial
value.
s Rotates the attribute used to sort the list of
probes.
t Brings up a prompt to allow toggling(on/off) of
probes by index. Probe points are still affected by
their conditions.
r Resumes the script by toggling on all probes.
p Pauses the script by toggling off all probes.
x Hides/shows the status window. This allows for more
output to be seen.
navigation-keys
The navigation keys can be used to scroll up and
down the windows.
Tab Toggle scrolling between status and output windows.
--example
This option is used to run example scripts without having
to enter the entire path to the script. Example scripts
can be found in the directory specified in the
stappaths(7) manual page.
--no-global-var-display
This option is used to disable the automatic logging of
unused global variables at the end of a stap session.
