<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<chapter id="using-systemtap">
	<title>Using SystemTap</title>
	<remark>
		short intro, contents of chapter
	</remark>
	<indexterm>
		<primary>Using SystemTap</primary>
	</indexterm>


	<para>
		This chapter documents how to install SystemTap in the system and explains how to use the <command>stap</command> utility to run SystemTap scripts.
	</para>
	<xi:include href="Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<xi:include href="CrossInstrumenting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
	<section id="using-usage">
		<title>Running SystemTap Scripts</title>
		<remark>
			- 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)
		</remark>

		<remark>
			- running systemtap scripts
		</remark>
<!--
		<remark>- Tapsets: short intro on usage</remark>
		-->
<indexterm>
<primary>Usage</primary>
<secondary>running SystemTap scripts</secondary>
</indexterm>

<indexterm>
<primary>running SystemTap scripts</primary>
<secondary>Usage</secondary>
</indexterm>

<indexterm>
	<primary>Usage</primary>
	<secondary>stap</secondary>
</indexterm>

<indexterm>
	<primary>stap</primary>
	<secondary>Usage</secondary>
</indexterm>
<!-- next 2 indexterms for staprun -->

<indexterm>
	<primary>Usage</primary>
	<secondary>staprun</secondary>
</indexterm>

<indexterm>
	<primary>staprun</primary>
	<secondary>Usage</secondary>
</indexterm>
		<para>
			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.
		</para>

<!--
<important>
	<title>Important</title>
<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>

</important>
		-->

<!--<formalpara>
	<title>stapdev and stapusr</title>-->

<indexterm>
<primary>SystemTap scripts, how to run</primary>
</indexterm>
	<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>
<!-- </formalpara> -->

<variablelist>

<varlistentry>
	<term>stapdev</term>
	<listitem>
<indexterm>
<primary>Usage</primary>
<secondary>stapdev</secondary>
</indexterm>

<indexterm>
<primary>stapdev</primary>
<secondary>Usage</secondary>
</indexterm>
<para>
	Members of this group can use the <command>stap</command> command to run SystemTap scripts, or <command>staprun</command> to run SystemTap instrumentation modules.
</para>


<para>
	Running the <command>stap</command> command involves compiling SystemTap scripts into kernel modules and
	loading them into the kernel. This operation requires elevated privileges to the system, which are granted
	to <systemitem class="groupname">stapdev</systemitem> members. Unfortunately, such privileges also grant effective root
	access to <systemitem class="groupname">stapdev</systemitem> members. As a consequence, only grant
	<systemitem class="groupname">stapdev</systemitem> group membership to users whom you can trust with root access.
</para>

	</listitem>
</varlistentry>

<varlistentry>
	<term>stapusr</term>
	<listitem>
<indexterm>
<primary>Usage</primary>
<secondary>stapusr</secondary>
</indexterm>

<indexterm>
<primary>stapusr</primary>
<secondary>Usage</secondary>
</indexterm>
<para>
	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.
</para>
</listitem>
</varlistentry>
</variablelist>


		<para>
			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:
		</para>
		<screen><command>stap <replaceable>file_name</replaceable></command></screen>

<indexterm>
	<primary>Usage</primary>
	<secondary>standard input, running scripts from</secondary>
</indexterm>

<indexterm>
	<primary>standard input, running scripts from</primary>
	<secondary>Usage</secondary>
</indexterm>
<indexterm>
	<primary>running scripts from standard input</primary>
</indexterm>

		<para>
			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:
		</para>
		<screen><command>echo "probe timer.s(1) {exit()}" | stap -v -</command></screen>

		<para> Below is a list of commonly used <command>stap</command> options: </para>
<indexterm>
<primary>Usage</primary>
<secondary>options, stap</secondary>
</indexterm>

<indexterm>
<primary>options, stap</primary>
<secondary>Usage</secondary>
</indexterm>
<variablelist>

<indexterm>
<primary>stap options</primary>
</indexterm>

<varlistentry>
	<term>-v</term>
	<listitem>
		<para>Makes the output of the SystemTap session more
		verbose. You can repeat this option multiple times to provide more details on the script's execution,
		for example:</para>

		<screen><command>stap -vvv script.stp</command></screen>
		
		<para>This option is particularly useful if you encounter any errors in running the script.
		For more information about common SystemTap script errors, refer to <xref linkend="errors"/>.</para>
	</listitem>
</varlistentry>

<varlistentry>
	<term>-o <replaceable>file_name</replaceable></term>
	<listitem>
		<para>Sends the standard output to a file named <replaceable>file_name</replaceable>.</para>
	</listitem>
</varlistentry>

<varlistentry>
	<term>-S <replaceable>size</replaceable>,<replaceable>count</replaceable></term>
	<listitem>
	  <para>Limits the maximum size of output files to <replaceable>size</replaceable> megabytes and
	    the maximum number of stored files to
	    <replaceable>count</replaceable>. This option implements logrotate operations for SystemTap
			and the resulting file names have a sequence number suffix.</para>
	</listitem>
</varlistentry>

<varlistentry>
	<term>-x <replaceable>process_id</replaceable></term>
	<listitem>
		<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>
	</listitem>
</varlistentry>

<varlistentry>
	<term>-c '<replaceable>command</replaceable>'</term>
	<listitem>

		<para>Sets the SystemTap handler function
		<function>target()</function> to the specified
		command and runs the SystemTap instrumentation for the duration
		of this command.
		For more information about
		<function>target()</function>, refer to <xref
		linkend="systemtapscript-functions"/>.</para>

	</listitem>
</varlistentry>
<!--
<varlistentry>
	<term></term>
	<listitem>
		<para></para>
	</listitem>
</varlistentry>
			-->
<varlistentry>
	<term>-e '<replaceable>script</replaceable>'</term>
	<listitem>
	  <para>Uses <replaceable>script</replaceable> rather than a file as input for the SystemTap translator.</para>
	</listitem>
</varlistentry>

<varlistentry>
	<term>-F</term>
	<listitem>
	  <para>Uses SystemTap's flight recorder mode and makes the script a
	  background process. For more information about flight
	  recorder mode, refer to <xref linkend="flight-recorder"/>.</para>
	</listitem>
</varlistentry>
</variablelist>

<remark>any other useful options worth noting here for beginners?</remark>

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

<section id="flight-recorder">
<title>SystemTap Flight Recorder Mode</title>
<indexterm>
<primary>flight recorder mode</primary>
</indexterm>

<para>
SystemTap's flight recorder mode allows you to run a SystemTap script
for long periods of time and just focus on recent output. The flight
recorder mode limits the amount of output
generated.
</para>
<para>
There are two variations of the flight recorder mode:
<firstterm>in-memory</firstterm> and <firstterm>file</firstterm> mode.
In both cases, the SystemTap script runs as a
background process.
</para>

<section id="memory-flight-recorder">
<title>In-memory Flight Recorder</title>
<indexterm>
<primary>flight recorder mode</primary>
<secondary>in-memory mode</secondary>
</indexterm>

<para>
When flight recorder mode is used without a
file name, SystemTap uses a buffer in kernel memory to store the output of the
script. Once the SystemTap instrumentation module is loaded and the probes start
running, the instrumentation detaches and is put in the background. When
the interesting event occurs, you can reattach to the instrumentation to see
the recent output in the memory buffer and any continuing output.
</para>

<para>
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:
</para>

<screen><command>stap -F iotime.stp</command></screen>

<para>
Once the script starts, <command>stap</command> prints a message similar to
the following to provide you with the command to reconnect to the running
script:
</para>

<screen>Disconnecting from systemtap module.
To reconnect, type "staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556"</screen>

<para>
When the interesting event occurs, run the following command to connect
to the currently running script, output the recent data in the memory buffer,
and get continuing output:
</para>

<screen><command>staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556</command></screen>

<para>
By default, the kernel buffer is 1MB in size. You can increase this value by
using the <option>-s</option> option with the size in megabytes (rounded up to the
next power over 2) for the buffer. For example, <option>-s2</option> on the
SystemTap command line would specify 2MB for the buffer.
</para>
</section>

<section id="file-flight-recorder">
<title>File Flight Recorder</title>
<indexterm>
<primary>flight recorder mode</primary>
<secondary>file mode</secondary>
</indexterm>

<para>
The flight recorder mode can also store data to files. You can control the number and size of
the files kept by using the <option>-S</option> option followed by two
numerical arguments separated by a comma: the first argument is the maximum size
in megabytes for the each output file, the second argument is the number of
recent files to keep. To specify the file name, use the <option>-o</option>
option followed by the name. SystemTap automatically adds a number suffix to the file name
to indicate the order of the files.
</para>
<para>
The following command starts SystemTap in file
flight recorder mode with the output going to files named
<filename>/tmp/pfaults.log.<replaceable>[0-9]+</replaceable></filename>, each
file 1MB or smaller, and keeping latest two files:
</para>

<screen><command>stap -F -o /tmp/pfaults.log -S 1,2  pfaults.stp</command></screen>

<para>
The command prints the process ID to standard output. Sending a SIGTERM to
the process terminates the SystemTap script and stops the data collection. For
example, if the previous command listed 7590 as the process ID, the following
command would stop the SystemTap script:
</para>

<screen><command>kill -s SIGTERM 7590</command></screen>

<para>
In this example, only the most recent two files generated by the script are
kept: SystemTap automatically removes older files. As a result, the
<command>ls -sh /tmp/pfaults.log.*</command> command lists two files:
</para>

<screen>1020K /tmp/pfaults.log.5    44K /tmp/pfaults.log.6</screen>

<para>
To examine the latest data, read the file with the highest number, in this case
<filename>/tmp/pfaults.log.6</filename>.
</para>

</section>
</section>
	</section>

</chapter>