Debian Codegraph @

README

raw
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