| 1 |
systemtap: a linux trace/probe tool |
| 2 |
|
| 3 |
Visit the project web site at <http://sourceware.org/systemtap>, |
| 4 |
for documentation and mailing lists for developers and users. |
| 5 |
|
| 6 |
This is free software. |
| 7 |
See the COPYING file for redistribution/modification terms. |
| 8 |
See the INSTALL file for generic build instructions. |
| 9 |
See the HACKING file for contribution advice. |
| 10 |
|
| 11 |
Prerequisites: |
| 12 |
|
| 13 |
- linux kernel |
| 14 |
- kernel module build environment (kernel-devel rpm) and/or dyninst |
| 15 |
- optionally, debugging information for kernel/user-space being instrumented |
| 16 |
- C compiler (same as what kernel was compiled with), to build kernel modules |
| 17 |
- C++11 compiler such as gcc 4.8+, to build systemtap itself |
| 18 |
- elfutils 0.151+ with libdwfl for debugging information parsing |
| 19 |
- Python for tools which are scripts, such as dtrace(1) |
| 20 |
- root privileges |
| 21 |
|
| 22 |
Installation steps: |
| 23 |
|
| 24 |
- If equipped with elfutils version 0.178 or later, try using debuginfod |
| 25 |
for automatic debuginfo downloading. This experimental public server |
| 26 |
may be enough: |
| 27 |
% export DEBUGINFOD_URLS=https://debuginfod.elfutils.org/ |
| 28 |
% export DEBUGINFOD_PROGRESS=1 |
| 29 |
See https://sourceware.org/elfutils/Debuginfod.html for more details. |
| 30 |
|
| 31 |
- Otherwise, install any debuginfo packages you need, for kernel |
| 32 |
and/or userspace. On modern Fedora, # debuginfo-install kernel [...] |
| 33 |
|
| 34 |
(Beware of confusion between kernel vs. kernel-debug vs kernel-PAE etc. |
| 35 |
variants. Each likely has a corresponding development and debuginfo |
| 36 |
package.) |
| 37 |
|
| 38 |
- Install the systemtap package. |
| 39 |
On modern Fedora, # yum install systemtap systemtap-runtime |
| 40 |
|
| 41 |
Build steps: |
| 42 |
|
| 43 |
- Consider installing the kernel-debuginfo, kernel-devel, gcc and |
| 44 |
dependent packages (or see below if you are building your own |
| 45 |
kernels from source). If using only the pure-userspace dyninst |
| 46 |
backend, install gcc and dyninst-devel. |
| 47 |
|
| 48 |
- If available, install your distribution's copy of elfutils and its |
| 49 |
development headers/libraries. |
| 50 |
Or if desired, build elfutils separately one time, and install |
| 51 |
it to /usr/local. |
| 52 |
See https://elfutils.org/ |
| 53 |
elfutils version 0.178 introduces automatic debuginfo downloading, |
| 54 |
which can makes systemtap usage easier. |
| 55 |
|
| 56 |
- On modern Fedora, install general optional build-requisites: |
| 57 |
# yum-builddep systemtap |
| 58 |
On modern Debian/Ubuntu, similarly: |
| 59 |
# apt-get build-dep systemtap |
| 60 |
|
| 61 |
- Download systemtap sources: |
| 62 |
https://sourceware.org/systemtap/ftp/releases/ |
| 63 |
https://sourceware.org/systemtap/ftp/snapshots/ |
| 64 |
(or) |
| 65 |
git clone git://sourceware.org/git/systemtap.git |
| 66 |
(or) https://sourceware.org/git/systemtap.git |
| 67 |
|
| 68 |
- Build systemtap normally: |
| 69 |
% .../configure [other autoconf options] |
| 70 |
Add env LDFLAGS=-L/path/ CPPFLAGS=-I/path/ before configure |
| 71 |
to locate libraries in non-system directories. |
| 72 |
|
| 73 |
Consider configuring with "--prefix=DIRECTORY" to specify an |
| 74 |
installation directory other than /usr/local. It can be an ordinary |
| 75 |
personal directory. |
| 76 |
|
| 77 |
% make all |
| 78 |
# make install |
| 79 |
To uninstall systemtap: |
| 80 |
# make uninstall |
| 81 |
|
| 82 |
Alternately, on a Fedora-like system: |
| 83 |
% make rpm |
| 84 |
# rpm -i /path/to/rpmbuild/.../systemtap*rpm |
| 85 |
|
| 86 |
|
| 87 |
- Run systemtap: |
| 88 |
|
| 89 |
To run systemtap after installation, add $prefix/bin to your $PATH, or |
| 90 |
refer to $prefix/bin/stap directly. If you keep your build tree |
| 91 |
around, you can also use the "stap" binary there. |
| 92 |
|
| 93 |
Some samples should be available under $prefix/share/doc/systemtap/examples. |
| 94 |
|
| 95 |
For the normal linux-kernel-module based backend, run "stap" as |
| 96 |
root. If desired, create "stapdev" and "stapusr" entries in |
| 97 |
/etc/groups. Any users in "stapdev"+"stapusr" will be able to run |
| 98 |
systemtap as if with root privileges. Users in "stapusr" only may |
| 99 |
launch (with "staprun") pre-compiled probe modules (created by "stap |
| 100 |
-p4 ...") that a system administrator copied under |
| 101 |
/lib/modules/`uname -r`/systemtap. "stapusr" may also be permitted |
| 102 |
to create arbitrary unprivileged systemtap scripts of their own. |
| 103 |
See README.unprivileged for additional setup instructions. |
| 104 |
|
| 105 |
To run a simple test. |
| 106 |
# stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}' |
| 107 |
|
| 108 |
To run the full test suite from the build tree, install dejagnu, |
| 109 |
then run with root privileges: |
| 110 |
# make installcheck |
| 111 |
|
| 112 |
For the prototype dyninst pure-userspace backend, run "stap" as any user. |
| 113 |
% stap --runtime=dyninst -e 'probe process.function("*") { |
| 114 |
println(pn(), ":", $$parms) }' -c 'ls' |
| 115 |
|
| 116 |
For the prototype bpf backend, run "stap" as "root" |
| 117 |
# stap --runtime=bpf -e 'probe kernel.function("do_exit") { |
| 118 |
printf("bye %d\n", pid()) }' |
| 119 |
|
| 120 |
|
| 121 |
|
| 122 |
Tips: |
| 123 |
|
| 124 |
- By default, systemtap looks for the debug info in these locations: |
| 125 |
/boot/vmlinux-`uname -r` |
| 126 |
/usr/lib/debug/lib/modules/`uname -r`/vmlinux |
| 127 |
/lib/modules/`uname -r`/vmlinux |
| 128 |
/lib/modules/`uname -r`/build/vmlinux |
| 129 |
|
| 130 |
|
| 131 |
Building a kernel.org kernel: |
| 132 |
|
| 133 |
- Build the kernel using your normal procedures. Enable |
| 134 |
CONFIG_DEBUG_INFO, CONFIG_KPROBES, CONFIG_RELAY, CONFIG_DEBUG_FS, |
| 135 |
CONFIG_MODULES, CONFIG_MODULE_UNLOAD, CONFIG_UPROBES if able |
| 136 |
- % make modules_install install headers_install |
| 137 |
- Boot into the kernel. |
| 138 |
|
| 139 |
- If you wish to leave the kernel build tree in place, simply run |
| 140 |
% stap -r /path/to/kernel/build/tree [...] |
| 141 |
You're done. |
| 142 |
|
| 143 |
- Or else, if you wish to install the kernel build/debuginfo data into |
| 144 |
a place where systemtap will find it without the "-r" option: |
| 145 |
% ln -s /path/to/kernel/build/tree /lib/modules/RELEASE/build |
| 146 |
|
| 147 |
- Instead of using the "-r" option, you can also use the environment |
| 148 |
variable SYSTEMTAP_RELEASE to direct systemtap to the kernel data. |
| 149 |
|