Debian Codegraph @

doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml

raw
1 <?xml version='1.0'?>
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3 ]>
4
5 <chapter id="using-systemtap">
6 <title>Using SystemTap</title>
7 <remark>
8 short intro, contents of chapter
9 </remark>
10 <indexterm>
11 <primary>Using SystemTap</primary>
12 </indexterm>
13
14
15 <para>
16 This chapter documents how to install SystemTap in the system and explains how to use the <command>stap</command> utility to run SystemTap scripts.
17 </para>
18 <xi:include href="Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
19 <xi:include href="CrossInstrumenting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
20 <section id="using-usage">
21 <title>Running SystemTap Scripts</title>
22 <remark>
23 - basic commands (e.g. stap), useful options per command (e.g. stap -vv), tool references (man pages, related kernel-doc), references within book (i.e. errors chapter)
24 </remark>
25
26 <remark>
27 - running systemtap scripts
28 </remark>
29 <!--
30 <remark>- Tapsets: short intro on usage</remark>
31 -->
32 <indexterm>
33 <primary>Usage</primary>
34 <secondary>running SystemTap scripts</secondary>
35 </indexterm>
36
37 <indexterm>
38 <primary>running SystemTap scripts</primary>
39 <secondary>Usage</secondary>
40 </indexterm>
41
42 <indexterm>
43 <primary>Usage</primary>
44 <secondary>stap</secondary>
45 </indexterm>
46
47 <indexterm>
48 <primary>stap</primary>
49 <secondary>Usage</secondary>
50 </indexterm>
51 <!-- next 2 indexterms for staprun -->
52
53 <indexterm>
54 <primary>Usage</primary>
55 <secondary>staprun</secondary>
56 </indexterm>
57
58 <indexterm>
59 <primary>staprun</primary>
60 <secondary>Usage</secondary>
61 </indexterm>
62 <para>
63 SystemTap is distributed with a number of command line tools that allow you to monitor the activities of the system. The <command>stap</command> command reads probing instructions from a SystemTap script, translates these instructions into C code, builds a kernel module, and loads it into the running Linux kernel. The <command>staprun</command> command runs SystemTap instrumentation, that is, a kernel module built from SystemTap scripts during a cross-instrumentation.
64 </para>
65
66 <!--
67 <important>
68 <title>Important</title>
69 <para>Running SystemTap requires root privileges. As such, you need to either log in as root or configure <command>sudo</command> accordingly for specific users who need to run SystemTap (refer to <command>man sudo</command> or <command>man visudo</command> for more information.</para>
70
71 </important>
72 -->
73
74 <!--<formalpara>
75 <title>stapdev and stapusr</title>-->
76
77 <indexterm>
78 <primary>SystemTap scripts, how to run</primary>
79 </indexterm>
80 <para>Running <command>stap</command> and <command>staprun</command> requires elevated privileges to the system. Because not all users can be granted root access just to run SystemTap, you can allow a non-privileged user to run SystemTap instrumentation on their machine by adding them to one of the following user groups:</para>
81 <!-- </formalpara> -->
82
83 <variablelist>
84
85 <varlistentry>
86 <term>stapdev</term>
87 <listitem>
88 <indexterm>
89 <primary>Usage</primary>
90 <secondary>stapdev</secondary>
91 </indexterm>
92
93 <indexterm>
94 <primary>stapdev</primary>
95 <secondary>Usage</secondary>
96 </indexterm>
97 <para>
98 Members of this group can use the <command>stap</command> command to run SystemTap scripts, or <command>staprun</command> to run SystemTap instrumentation modules.
99 </para>
100
101
102 <para>
103 Running the <command>stap</command> command involves compiling SystemTap scripts into kernel modules and
104 loading them into the kernel. This operation requires elevated privileges to the system, which are granted
105 to <systemitem class="groupname">stapdev</systemitem> members. Unfortunately, such privileges also grant effective root
106 access to <systemitem class="groupname">stapdev</systemitem> members. As a consequence, only grant
107 <systemitem class="groupname">stapdev</systemitem> group membership to users whom you can trust with root access.
108 </para>
109
110 </listitem>
111 </varlistentry>
112
113 <varlistentry>
114 <term>stapusr</term>
115 <listitem>
116 <indexterm>
117 <primary>Usage</primary>
118 <secondary>stapusr</secondary>
119 </indexterm>
120
121 <indexterm>
122 <primary>stapusr</primary>
123 <secondary>Usage</secondary>
124 </indexterm>
125 <para>
126 Members of this group can only use the <command>staprun</command> command to run SystemTap instrumentation modules. In addition, they can only run modules from the <filename class="directory">/lib/modules/<replaceable>kernel_version</replaceable>/systemtap/</filename> directory. Note that this directory must be owned only by the root user, and must only be writable by the root user.
127 </para>
128 </listitem>
129 </varlistentry>
130 </variablelist>
131
132
133 <para>
134 The <command>stap</command> command reads a SystemTap script either from a file, or from standard input. To tell <command>stap</command> to read a SystemTap script from a file, specify the file name on the command line:
135 </para>
136 <screen><command>stap <replaceable>file_name</replaceable></command></screen>
137
138 <indexterm>
139 <primary>Usage</primary>
140 <secondary>standard input, running scripts from</secondary>
141 </indexterm>
142
143 <indexterm>
144 <primary>standard input, running scripts from</primary>
145 <secondary>Usage</secondary>
146 </indexterm>
147 <indexterm>
148 <primary>running scripts from standard input</primary>
149 </indexterm>
150
151 <para>
152 To instruct <command>stap</command> to read a SystemTap script from standard input, use the <option>-</option> switch instead of the file name. Note that any command-line options you wish to use must be inserted before the <option>-</option> switch. For example, to make the output of the <command>stap</command> command more verbose, type:
153 </para>
154 <screen><command>echo "probe timer.s(1) {exit()}" | stap -v -</command></screen>
155
156 <para> Below is a list of commonly used <command>stap</command> options: </para>
157 <indexterm>
158 <primary>Usage</primary>
159 <secondary>options, stap</secondary>
160 </indexterm>
161
162 <indexterm>
163 <primary>options, stap</primary>
164 <secondary>Usage</secondary>
165 </indexterm>
166 <variablelist>
167
168 <indexterm>
169 <primary>stap options</primary>
170 </indexterm>
171
172 <varlistentry>
173 <term>-v</term>
174 <listitem>
175 <para>Makes the output of the SystemTap session more
176 verbose. You can repeat this option multiple times to provide more details on the script's execution,
177 for example:</para>
178
179 <screen><command>stap -vvv script.stp</command></screen>
180
181 <para>This option is particularly useful if you encounter any errors in running the script.
182 For more information about common SystemTap script errors, refer to <xref linkend="errors"/>.</para>
183 </listitem>
184 </varlistentry>
185
186 <varlistentry>
187 <term>-o <replaceable>file_name</replaceable></term>
188 <listitem>
189 <para>Sends the standard output to a file named <replaceable>file_name</replaceable>.</para>
190 </listitem>
191 </varlistentry>
192
193 <varlistentry>
194 <term>-S <replaceable>size</replaceable>,<replaceable>count</replaceable></term>
195 <listitem>
196 <para>Limits the maximum size of output files to <replaceable>size</replaceable> megabytes and
197 the maximum number of stored files to
198 <replaceable>count</replaceable>. This option implements logrotate operations for SystemTap
199 and the resulting file names have a sequence number suffix.</para>
200 </listitem>
201 </varlistentry>
202
203 <varlistentry>
204 <term>-x <replaceable>process_id</replaceable></term>
205 <listitem>
206 <para>Sets the SystemTap handler function <function>target()</function> to the specified process ID. For more information about <function>target()</function>, refer to <xref linkend="systemtapscript-functions"/>.</para>
207 </listitem>
208 </varlistentry>
209
210 <varlistentry>
211 <term>-c '<replaceable>command</replaceable>'</term>
212 <listitem>
213
214 <para>Sets the SystemTap handler function
215 <function>target()</function> to the specified
216 command and runs the SystemTap instrumentation for the duration
217 of this command.
218 For more information about
219 <function>target()</function>, refer to <xref
220 linkend="systemtapscript-functions"/>.</para>
221
222 </listitem>
223 </varlistentry>
224 <!--
225 <varlistentry>
226 <term></term>
227 <listitem>
228 <para></para>
229 </listitem>
230 </varlistentry>
231 -->
232 <varlistentry>
233 <term>-e '<replaceable>script</replaceable>'</term>
234 <listitem>
235 <para>Uses <replaceable>script</replaceable> rather than a file as input for the SystemTap translator.</para>
236 </listitem>
237 </varlistentry>
238
239 <varlistentry>
240 <term>-F</term>
241 <listitem>
242 <para>Uses SystemTap's flight recorder mode and makes the script a
243 background process. For more information about flight
244 recorder mode, refer to <xref linkend="flight-recorder"/>.</para>
245 </listitem>
246 </varlistentry>
247 </variablelist>
248
249 <remark>any other useful options worth noting here for beginners?</remark>
250
251 <para>For more information about the <command>stap</command> command, refer to the <citerefentry><refentrytitle>stap</refentrytitle><manvolnum>1</manvolnum></citerefentry> man page. For more information about the <command>staprun</command> command and cross-instrumentation, refer to <xref linkend="cross-compiling" /> or the <citerefentry><refentrytitle>staprun</refentrytitle><manvolnum>8</manvolnum></citerefentry> man page.</para>
252
253 <section id="flight-recorder">
254 <title>SystemTap Flight Recorder Mode</title>
255 <indexterm>
256 <primary>flight recorder mode</primary>
257 </indexterm>
258
259 <para>
260 SystemTap's flight recorder mode allows you to run a SystemTap script
261 for long periods of time and just focus on recent output. The flight
262 recorder mode limits the amount of output
263 generated.
264 </para>
265 <para>
266 There are two variations of the flight recorder mode:
267 <firstterm>in-memory</firstterm> and <firstterm>file</firstterm> mode.
268 In both cases, the SystemTap script runs as a
269 background process.
270 </para>
271
272 <section id="memory-flight-recorder">
273 <title>In-memory Flight Recorder</title>
274 <indexterm>
275 <primary>flight recorder mode</primary>
276 <secondary>in-memory mode</secondary>
277 </indexterm>
278
279 <para>
280 When flight recorder mode is used without a
281 file name, SystemTap uses a buffer in kernel memory to store the output of the
282 script. Once the SystemTap instrumentation module is loaded and the probes start
283 running, the instrumentation detaches and is put in the background. When
284 the interesting event occurs, you can reattach to the instrumentation to see
285 the recent output in the memory buffer and any continuing output.
286 </para>
287
288 <para>
289 To run a SystemTap script by using the flight recorder in-memory mode, run the <command>stap</command> command with the <option>-F</option> command line option:
290 </para>
291
292 <screen><command>stap -F iotime.stp</command></screen>
293
294 <para>
295 Once the script starts, <command>stap</command> prints a message similar to
296 the following to provide you with the command to reconnect to the running
297 script:
298 </para>
299
300 <screen>Disconnecting from systemtap module.
301 To reconnect, type "staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556"</screen>
302
303 <para>
304 When the interesting event occurs, run the following command to connect
305 to the currently running script, output the recent data in the memory buffer,
306 and get continuing output:
307 </para>
308
309 <screen><command>staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556</command></screen>
310
311 <para>
312 By default, the kernel buffer is 1MB in size. You can increase this value by
313 using the <option>-s</option> option with the size in megabytes (rounded up to the
314 next power over 2) for the buffer. For example, <option>-s2</option> on the
315 SystemTap command line would specify 2MB for the buffer.
316 </para>
317 </section>
318
319 <section id="file-flight-recorder">
320 <title>File Flight Recorder</title>
321 <indexterm>
322 <primary>flight recorder mode</primary>
323 <secondary>file mode</secondary>
324 </indexterm>
325
326 <para>
327 The flight recorder mode can also store data to files. You can control the number and size of
328 the files kept by using the <option>-S</option> option followed by two
329 numerical arguments separated by a comma: the first argument is the maximum size
330 in megabytes for the each output file, the second argument is the number of
331 recent files to keep. To specify the file name, use the <option>-o</option>
332 option followed by the name. SystemTap automatically adds a number suffix to the file name
333 to indicate the order of the files.
334 </para>
335 <para>
336 The following command starts SystemTap in file
337 flight recorder mode with the output going to files named
338 <filename>/tmp/pfaults.log.<replaceable>[0-9]+</replaceable></filename>, each
339 file 1MB or smaller, and keeping latest two files:
340 </para>
341
342 <screen><command>stap -F -o /tmp/pfaults.log -S 1,2 pfaults.stp</command></screen>
343
344 <para>
345 The command prints the process ID to standard output. Sending a SIGTERM to
346 the process terminates the SystemTap script and stops the data collection. For
347 example, if the previous command listed 7590 as the process ID, the following
348 command would stop the SystemTap script:
349 </para>
350
351 <screen><command>kill -s SIGTERM 7590</command></screen>
352
353 <para>
354 In this example, only the most recent two files generated by the script are
355 kept: SystemTap automatically removes older files. As a result, the
356 <command>ls -sh /tmp/pfaults.log.*</command> command lists two files:
357 </para>
358
359 <screen>1020K /tmp/pfaults.log.5 44K /tmp/pfaults.log.6</screen>
360
361 <para>
362 To examine the latest data, read the file with the highest number, in this case
363 <filename>/tmp/pfaults.log.6</filename>.
364 </para>
365
366 </section>
367 </section>
368 </section>
369
370 </chapter>
371