revised as per wcohen, added new section iotime

9 files changed, 217 insertions, 17 deletions

diff --git a/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml b/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml
index 09530ccc..f2876aad 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml
@@ -4,11 +4,12 @@
 
 <bookinfo id="SystemTap_Beginners_Guide">
 	<title>SystemTap Beginners Guide</title>
-	<subtitle>For use with Red Hat Enterprise Linux 5</subtitle>
-	<edition>1.0</edition>
+	<subtitle condition="RedHat">Introduction to SystemTap (for Red Hat Enterprise Linux 5)</subtitle>
+	<subtitle condition="fedora">Introduction to SystemTap (for Fedora Core 10)</subtitle>
+	<edition>2.0</edition>
 	<productname>Red Hat Enterprise Linux</productname>
 	<productnumber>5.3</productnumber>
-	<pubsnumber>1</pubsnumber>
+	<pubsnumber>2</pubsnumber>
 	<abstract><para>This guide provides basic instructions on how to use SystemTap to monitor different subsystems of &PRODUCT; in finer detail. The <citetitle>SystemTap Beginners Guide</citetitle> is recommended for users who have taken <ulink url="https://www.redhat.com/courses/rh133_red_hat_linux_system_administration_and_rhct_exam/">RHCT</ulink> or have a similar level of expertise in &PRODUCT;.</para></abstract>
 	<corpauthor>
 		<inlinemediaobject>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Revision_History.xml b/doc/SystemTap_Beginners_Guide/en-US/Revision_History.xml
index d03a597b..d708da4f 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Revision_History.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Revision_History.xml
@@ -20,6 +20,21 @@
 					</simplelist>
 				</revdescription>
 			</revision>
+			
+			<revision>
+				<revnumber>2.0</revnumber>
+				<date>December 1, 2008</date>
+				<author>
+					<firstname>Don</firstname>
+					<surname>Domingo</surname>
+					<email>ddomingo@redhat.com</email>
+				</author>
+				<revdescription>
+					<simplelist>
+						<member>Content now complete, pending tech review and other feedback for one final push. Build also includes index.</member>
+					</simplelist>
+				</revdescription>
+			</revision>
 		</revhistory>
 	</simpara>
 </appendix>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml
index b57486d9..42f1986b 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml
@@ -108,7 +108,14 @@
 	
 <para>The time and date in the output of <xref linkend="scriptdisktop"/> is returned by the functions <command>ctime()</command> and <command>gettimeofday_s()</command>. <command>ctime()</command> derives calendar time in terms of seconds passed since the Unix epoch (January 1, 1970). <command>gettimeofday_s()</command> counts the <emphasis>actual</emphasis> number of seconds since Unix epoch, which gives a fairly accurate human-readable timestamp for the output.</para>
 	
-<remark>needinfo: what does $return do?</remark> 	
+<para>
+	In this script, the <command>$return</command> is a local variable that stores the
+	actual number of bytes each process reads or writes from the virtual file system. 
+	<command>$return</command> can only be used in return probes (e.g. 
+	<command>vfs.read.return</command> and <command>vfs.read.return</command>).
+</para>
+	
+<!--<remark>needinfo: what does $return do?</remark> 	-->
 <example id="disktopoutput">
 	<title><xref linkend="scriptdisktop"/> Sample Output</title>
 <screen>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml
new file mode 100644
index 00000000..21b6db9d
--- /dev/null
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml
@@ -0,0 +1,140 @@
+<?xml version='1.0'?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+	<section id="iotimesect">
+		<title>Tracking I/O Time For Each File Read or Write</title>
+<indexterm>
+<primary>script examples</primary>
+<secondary>monitoring I/O time</secondary>
+</indexterm>
+
+<indexterm>
+<primary>examples of SystemTap scripts</primary>
+<secondary>monitoring I/O time</secondary>
+</indexterm>
+
+<indexterm>
+<primary>monitoring I/O time</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<indexterm>
+<primary>I/O time, monitoring</primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<indexterm>
+<primary>time of I/O </primary>
+<secondary>examples of SystemTap scripts</secondary>
+</indexterm>
+
+<!-- 	<para>This section describes how to monitor I/O time on the system.</para> -->
+	
+<para>
+	This section describes how to monitor the amount of time it takes for each process to read 
+	from or write to any file. This is useful if you wish to determine what files are slow to 
+	load on a given system.
+</para>
+
+<formalpara id="iotime">
+	<title>iotime.stp</title>
+<para>
+<programlisting>
+<xi:include parse="text" href="extras/iotime-simple.stp" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</programlisting>
+</para>
+</formalpara>
+
+<para>
+	<xref linkend="iotime"/> tracks each time a system call opens, closes, reads from, and writes 
+	to a file. For each file any system call accesses, <xref linkend="iotime"/> counts the number 
+	of microseconds it takes for any reads or writes to finish and tracks the amount of data (in 
+	bytes) read from or written to the file.
+</para>
+
+<para>
+	<xref linkend="iotime"/> also uses the local variable <command>$count</command> to track the 
+	amount of data (in bytes) that any system call <emphasis>attempts</emphasis> to read or 
+	write. Note that <command>$return</command> (as used in <xref linkend="scriptdisktop"/> from 
+	<xref linkend= "disktop"/>) stores the <emphasis>actual</emphasis> amount of data 
+	read/written. <command>$count</command> can only be used on probes that track data reads or 
+	writes (e.g. <command>syscall.read</command> and <command>syscall.write</command>).
+</para>
+
+<!--<remark>what does $count do, specifically?</remark>-->
+
+<example id="iotimeoutput">
+	<title><xref linkend="iotime"/> Sample Output</title>
+<screen>
+[...]
+3123380 2460 (pcscd) access /dev/bus/usb/005/001 read: 0 write: 0

+825946 3364 (NetworkManager) access /sys/class/net/eth0/carrier read: 8190 write: 0

+825955 3364 (NetworkManager) iotime /sys/class/net/eth0/carrier time: 9

+117061 2460 (pcscd) access /dev/bus/usb/003/001 read: 43 write: 0

+117065 2460 (pcscd) iotime /dev/bus/usb/003/001 time: 7

+3973737 2886 (sendmail) access /proc/loadavg read: 4096 write: 0

+3973744 2886 (sendmail) iotime /proc/loadavg time: 11

+[...]
+</screen>
+</example>
+
+<para>
+	<xref linkend="iotimeoutput"/> prints out the following data: 
+</para>	
+
+<itemizedlist>
+	<listitem><para>A timestamp, in microseconds</para></listitem>
+	<listitem><para>Process ID and process name</para></listitem>
+	<listitem><para>An <computeroutput>access</computeroutput> or  
+		<computeroutput>iotime</computeroutput> flag</para></listitem>   
+	<listitem><para>The file accessed</para></listitem>
+</itemizedlist>
+
+<para>
+	If a process was able to read or write any data, a pair of 
+	<computeroutput>access</computeroutput> and <computeroutput>iotime</computeroutput> lines 
+	should appear together. The <computeroutput>access</computeroutput> line's timestamp refer to 
+	the time that a given process started accessing a file; at the end of the line, it will show 
+	the amount of data read/written (in bytes). The <computeroutput>iotime</computeroutput> line 
+	will show the amount of time (in microseconds) that the process took in order to perform the 
+	read or write.
+</para>
+
+<para>
+	If an <computeroutput>access</computeroutput> line is not followed by an
+	<computeroutput>iotime</computeroutput> line, it simply means that the process did not read 
+	or write any data.
+</para>
+
+<!--
+<para><xref linkend="iotopoutput"/> displays top I/O writes and reads within a random 10-second interval. Note that <xref linkend="iotop"/> also detects I/O resulting from SystemTap activity &mdash; <xref linkend="iotopoutput"/> displays reads done by <command>staprun</command>.</para>-->
+<!--
+global reads, writes, total_io
+
+probe kernel.function("vfs_read") {
+reads[execname()] += $count
+}
+
+probe kernel.function("vfs_write") {
+writes[execname()] += $count
+}
+
+# print top 10 IO processes every 5 seconds
+probe timer.s(5) {
+foreach (name in writes)
+total_io[name] += writes[name]
+foreach (name in reads)
+total_io[name] += reads[name]
+printf ("%16s\t%10s\t%10s\n", "Process", "KB Read", "KB Written")
+foreach (name in total_io- limit 10)
+printf("%16s\t%10d\t%10d\n", name,
+reads[name]/1024, writes[name]/1024)
+delete reads
+delete writes
+delete total_io
+print("\n")
+}
+-->
+
+</section>
\ No newline at end of file
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml
index 8ec2af90..c5bbb480 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml
@@ -40,7 +40,7 @@
 </para>
 </formalpara>
 
-<remark>what does $count do, specifically?</remark>
+<!-- <remark>what does $count do, specifically?</remark> -->
 
 <para><xref linkend="iotop"/> prints out the top ten executables generating I/O traffic every 5-second interval, in descending order. Its output contains the process name and the amount of data read or written by the process, in KB. For example:</para>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml
index e05e2bcf..301042f5 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml
@@ -92,8 +92,17 @@
 <secondary>examples of SystemTap scripts</secondary>
 </indexterm>
 <itemizedlist>
-	<listitem><para>A <firstterm>trigger function</firstterm> (<command>@1</command>), which enables or disables tracing on a per-thread basis.</para></listitem>
-	<listitem><para>The kernel function whose entry/exit call you'd like to trace (<command>@2</command>).</para></listitem>
+
+	<listitem><para>
+			A <firstterm>trigger function</firstterm> (<command>@1</command>), which 
+			enables or disables tracing on a per-thread basis. Tracing in each thread 
+			will continue as long as the trigger function has not exited yet.  
+		</para></listitem>
+	
+	<listitem><para>
+			The kernel function/s whose entry/exit call you'd like to trace 
+			(<command>@2</command>). 
+		</para></listitem>
 </itemizedlist>
 
 <remark> please verify previous if correct; i'm particularly interested in finding out how to better describe "trigger function"</remark>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml
index 0f914447..ab260d63 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml
@@ -46,10 +46,22 @@
 </programlisting>
 </para>
 </formalpara>
+<!--
+<remark>what do $return, $length, and $count return, specifically? when i substituted $return for $length here, script still ran but gave me bigger numbers. errored out with $length. where documented?</remark>-->
 
-<remark>what do $return, $length, and $count return, specifically? when i substituted $return for $length here, script still ran but gave me bigger numbers. errored out with $length. where documented?</remark>
+<para>
+	<xref linkend="traceio"/> prints the top ten executables generating I/O traffic over time. In
+	addition, it also tracks the cumulative amount of I/O reads and writes done by those ten 
+	executables. This information is tracked and printed out in 1-second intervals, and in 
+	descending order.
+</para>
+
+<para>
+	Note that <xref linkend="traceio"/> also uses the local variable <command>$return</command>,
+	which is also used by <xref linkend="scriptdisktop"/> from <xref linkend="disktop"/>.
+</para>
 
-<para><xref linkend="traceio"/> is similar to <xref linkend="iotop"/> (from <xref linkend="iotopsect"/>); both SystemTap scripts print out the top ten executables generating I/O traffic over time. However, <xref linkend="traceio"/> tracks the <emphasis>cumulative</emphasis> amount of I/O reads and writes done by the system's top ten executables. This information is tracked and printed out in 1-second intervals and in descending order.</para>
+<!--<para><xref linkend="traceio"/> is similar to <xref linkend="iotop"/> (from <xref linkend="iotopsect"/>); both SystemTap scripts print out the top ten executables generating I/O traffic over time. However, <xref linkend="traceio"/> tracks the <emphasis>cumulative</emphasis> amount of I/O reads and writes done by the system's top ten executables. This information is tracked and printed out in 1-second intervals and in descending order.</para>-->
 
 <example id="traceiooutput">
 	<title><xref linkend="traceio"/> Sample Output</title>
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml
index 6800adaa..4fc7ecc2 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml
@@ -125,9 +125,9 @@ semantic error: field 'f_dentry' not found
 </indexterm>	
 <para>The <command>usrdev2kerndev()</command> function converts the whole device number into the format understood by the kernel. The output produced by <command>usrdev2kerndev()</command> is used in conjunction with the <command>MKDEV()</command>, <command>MINOR()</command>, and <command>MAJOR()</command> functions to determine the major and minor numbers of a specific device.</para>
 
-<para>The output of <xref linkend="traceio2"/> includes the name and ID of any process performing a read/write, the function it is performing (i.e. <command>vfs_read</command> or <command>vfs_write</command>), and the device number (in hex format).</para>
-
-<remark>please verify if "0x800005" is "device number (in hex format)", and why it needs to be stated buy </remark>
+<para>The output of <xref linkend="traceio2"/> includes the name and ID of any process performing a read/write, the function it is performing (i.e. <command>vfs_read</command> or <command>vfs_write</command>), and the kernel device number.</para>
+<!--
+<remark>please verify if "0x800005" is "device number (in hex format)", and why it needs to be stated buy </remark>-->
 
 <para>The following example is an excerpt from the full output of <command>stap traceio2.stp 0x805</command>, where <literal>0x805</literal> is the whole device number of <filename>/home</filename>. <filename>/home</filename> resides in <filename>/dev/sda5</filename>, which is the device we wish to monitor.</para>
 
diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
index c17605db..8e089af6 100644
--- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
+++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml
@@ -36,22 +36,38 @@
 	<remark>case studies and more info on some scripts here - http://sourceware.org/systemtap/wiki/WarStories</remark>
 	
 <!-- 	<xi:include href="Useful_Scripts-Disk.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
+<xi:include href="Useful_Scripts-futexes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	
+<section id="mainsect-disk">
+	<title>Disk</title>
+	<para>The following sections showcase scripts that monitor disk and I/O activity.</para>
+	
 	<xi:include href="Useful_Scripts-disktop.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <!-- 	<xi:include href="Useful_Scripts-IO.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
-	<xi:include href="Useful_Scripts-iotop.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include href="Useful_Scripts-iotime.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-traceio.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />	
 	<xi:include href="Useful_Scripts-traceio2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 <!-- 	<xi:include href="Useful_Scripts-Kernel.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
-	<xi:include href="Useful_Scripts-paracallgraph.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-inodewatch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-	<xi:include href="Useful_Scripts-inodewatch2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />	
+	<xi:include href="Useful_Scripts-inodewatch2.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</section>
+
+<section id="mainsect-profiling">
+	<title>Profiling</title>
+	<para>The following sections showcase scripts that profile kernel activity by monitoring function calls.</para>
 	<xi:include href="Useful_Scripts-functioncalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include href="Useful_Scripts-paracallgraph.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+	<xi:include href="Useful_Scripts-threadtimes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</section>
 <!-- 	removed; handler function no longer working as expected
 	<xi:include href="Useful_Scripts-kernelprofiling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
-	<xi:include href="Useful_Scripts-futexes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<section id="mainsect-network">
+	<title>Network</title>
+	<para>The following sections showcase scripts that trace network-related functions and build a profile of network activity.</para>
 	<xi:include href="Useful_Scripts-nettop.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-sockettrace.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-	<xi:include href="Useful_Scripts-threadtimes.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</section>	
+
 <!--	<xi:include href="Useful_Scripts-Network.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-Signals.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
 	<xi:include href="Useful_Scripts-Syscalls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />