| 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 |
|