systemtap  4.4
About: SystemTap is a tool that allows developers and administrators to write and reuse simple scripts to deeply examine the activities of a live Linux system.
  Fossies Dox: systemtap-4.4.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

systemtap Documentation

Some Fossies usage hints in advance:

  1. To see the Doxygen generated documentation please click on one of the items in the steelblue colored "quick index" bar above or use the side panel at the left which displays a hierarchical tree-like index structure and is adjustable in width.
  2. If you want to search for something by keyword rather than browse for it you can use the client side search facility (using Javascript and DHTML) that provides live searching, i.e. the search results are presented and adapted as you type in the Search input field at the top right.
  3. Doxygen doesn't incorporate all member files but just a definable subset (basically the main project source code files that are written in a supported language). So to search and browse all member files you may visit the Fossies systemtap-4.4.tar.gz contents page and use the Fossies standard member browsing features (also with source code highlighting and additionally with optional code folding).
README
systemtap: a linux trace/probe tool

Visit the project web site at <http://sourceware.org/systemtap>,
for documentation and mailing lists for developers and users.

This is free software.
See the COPYING file for redistribution/modification terms.
See the INSTALL file for generic build instructions.
See the HACKING file for contribution advice.

Prerequisites:

- linux kernel
- kernel module build environment (kernel-devel rpm) and/or dyninst
- optionally, debugging information for kernel/user-space being instrumented
- C compiler (same as what kernel was compiled with), to build kernel modules
- C++11 compiler such as gcc 4.8+, to build systemtap itself
- elfutils 0.151+ with libdwfl for debugging information parsing
- root privileges

Installation steps:

- If equipped with elfutils version 0.178 or later, try using debuginfod
  for automatic debuginfo downloading.  This experimental public server
  may be enough:
  % export DEBUGINFOD_URLS=https://debuginfod.elfutils.org/
  % export DEBUGINFOD_PROGRESS=1
  See https://sourceware.org/elfutils/Debuginfod.html for more details.
  
- Otherwise, install any debuginfo packages you need, for kernel
  and/or userspace.  On modern Fedora, # debuginfo-install kernel [...]
  
  (Beware of confusion between kernel vs. kernel-debug vs kernel-PAE etc.
  variants.  Each likely has a corresponding development and debuginfo
  package.)

- Install the systemtap package.
  On modern Fedora, # yum install systemtap systemtap-runtime

Build steps:

- Consider installing the kernel-debuginfo, kernel-devel, gcc and
  dependent packages (or see below if you are building your own
  kernels from source).  If using only the pure-userspace dyninst
  backend, install gcc and dyninst-devel.
  
- If available, install your distribution's copy of elfutils and its
  development headers/libraries.
  Or if desired, build elfutils separately one time, and install
  it to /usr/local.
  See https://elfutils.org/
  elfutils version 0.178 introduces automatic debuginfo downloading,
  which can makes systemtap usage easier.

- On modern Fedora, install general optional build-requisites:
  # yum-builddep systemtap
  On modern Debian/Ubuntu, similarly:
  # apt-get build-dep systemtap

- Download systemtap sources:
  https://sourceware.org/systemtap/ftp/releases/
  https://sourceware.org/systemtap/ftp/snapshots/
  (or)
  git clone git://sourceware.org/git/systemtap.git
      (or) https://sourceware.org/git/systemtap.git

- Build systemtap normally:
  % .../configure [other autoconf options]
  Add env LDFLAGS=-L/path/ CPPFLAGS=-I/path/ before configure
  to locate libraries in non-system directories.

  Consider configuring with "--enable-dejazilla" to automatically
  contribute to our public test result database.

  Consider configuring with "--prefix=DIRECTORY" to specify an
  installation directory other than /usr/local.  It can be an ordinary
  personal directory.

  % make all
  # make install
  To uninstall systemtap:
  # make uninstall

  Alternately, on a Fedora-like system:
  % make rpm
  # rpm -i /path/to/rpmbuild/.../systemtap*rpm


- Run systemtap:

  To run systemtap after installation, add $prefix/bin to your $PATH, or
  refer to $prefix/bin/stap directly.  If you keep your build tree
  around, you can also use the "stap" binary there.  

  Some samples should be available under $prefix/share/doc/systemtap/examples.

  For the normal linux-kernel-module based backend, run "stap" as
  root.  If desired, create "stapdev" and "stapusr" entries in
  /etc/groups.  Any users in "stapdev"+"stapusr" will be able to run
  systemtap as if with root privileges.  Users in "stapusr" only may
  launch (with "staprun") pre-compiled probe modules (created by "stap
  -p4 ...") that a system administrator copied under
  /lib/modules/`uname -r`/systemtap.  "stapusr" may also be permitted
  to create arbitrary unprivileged systemtap scripts of their own.
  See README.unprivileged for additional setup instructions.

  To run a simple test.
  # stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'

  To run the full test suite from the build tree, install dejagnu,
  then run with root privileges:
  # make installcheck

  For the prototype dyninst pure-userspace backend, run "stap" as any user.
  % stap --runtime=dyninst -e 'probe process.function("*") { 
                               println(pn(), ":", $$parms) }' -c 'ls'

  For the prototype bpf backend, run "stap" as "root"
  # stap --runtime=bpf -e 'probe kernel.function("do_exit") {
                                 printf("bye %d\n", pid()) }'



Tips:

- By default, systemtap looks for the debug info in these locations:
  /boot/vmlinux-`uname -r`
  /usr/lib/debug/lib/modules/`uname -r`/vmlinux
  /lib/modules/`uname -r`/vmlinux
  /lib/modules/`uname -r`/build/vmlinux


Building a kernel.org kernel:

- Build the kernel using your normal procedures.  Enable
  CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS,
  CONFIG_MODULES, CONFIG_MODULE_UNLOAD, CONFIG_UPROBES if able
- % make modules_install install headers_install
- Boot into the kernel.

- If you wish to leave the kernel build tree in place, simply run
  % stap -r /path/to/kernel/build/tree [...]
  You're done.

- Or else, if you wish to install the kernel build/debuginfo data into
  a place where systemtap will find it without the "-r" option:
  % ln -s /path/to/kernel/build/tree /lib/modules/RELEASE/build 

- Instead of using the "-r" option, you can also use the environment 
  variable SYSTEMTAP_RELEASE to direct systemtap to the kernel data.